forked from MapServer/mapcache
/
INSTALL
191 lines (128 loc) · 7.26 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
Unix compilation instructions
-----------------------------
If you are using a git clone rather than a tarball distribution, you must first
run autoconf in the root directory, to create the configure file from configure.in:
$ autoconf
For unix users, the compilation process should resume to:
$ ./configure
$ make
(as root)
# make install-module
The installation script takes care of putting the built module in the apache module directory.
The process for activating a module is usually distro specific, but can be resumed by the
following snippet that should be present in the apache configuration file(s):
LoadModule mapcache_module modules/mod_mapcache.so
Next, a mapcache configuration is mapped to the server url with the following snippet
<IfModule mapcache_module>
<Directory /path/to/directory>
Order Allow,Deny
Allow from all
</Directory>
MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
</IfModule>
(as root)
# apachectl restart
If you have not disabled the demo service, you should now have access to it on
http://myserver/mapcache/demo
Customizing the build, or if something went wrong
-------------------------------------------------
mod-mapcache requires apache, libcurl, libjpeg and libpng development headers.
The configure script will try to locate them in default system locations, that can be
overriden or specified with switches (./configure --help should give you a full list):
apache apxs
===========
--with-apxs=/path/to/apxs
apxs is the apache extension tool that is used for building and installing the module to a local
apache instance. it should be installed along with a standard apache build, or supplied by
distros when installing the apache development packages.
apxs is sometimes called apxs2 (notably on debian)
apr
===
--with-apr-config=/path/to/apr-config
apr-config is sometimes called apr-1-config on some systems. The path to the apr libraries is susually determined
from the previous apxs utility. you can use this switch to override which apr will be used. beware that using a different
version of apr than the one that is linked to by apache will likely cause bugs.
apr-util
========
--with-apu-config=/path/to/apu-config
apu-config is sometimes called apu-1-config. the apr-util library is used to enable the memcached cache backend for
stroing tiles. If you don't plan on using it you can safely ignore or disable it.
libcurl
=======
--with-curl-config=/path/to/curl-config
libpng
======
--with-png=/path/to/png/prefix
this is the path where the libpng headers and libs can be located.
the configure script will be looking for [path]/include/png.h and [path]/lib/libpng.so
libjpeg
======
--with-jpeg=/path/to/jpeg/prefix
this is the path where the libjpeg headers and libs can be located.
the configure script will be looking for [path]/include/jpeg.h and [path]/lib/libjpeg.so
pixman (from 0.5 onwards) (recommended)
=======================================
--with-pixman=[yes|no|/path/to/pkgconfig/pixman.pc]
pixman is a pixel manipulation library used to assemble image tiles when responding
to non-tiled wms requests. Pixman support is recommended as it is highly optimized
and will take advantage of recent processor extensions (mms, sse, ...) to speed up
blending and resampling operations. In case the pixman library is not found, mod-mapcache
will fall back to internal pixel operations that are slower.
sqlite (from 0.5 onwards) (optional)
====================================
--with-sqlite[=/path/to/sqlite/prefix]
sqlite is used to enable the sqlite and mbtiles cache backend. version 3.5.0 or newer is
required.
gdal (from 0.4 onwards) (optional)
===================================
--with-gdal=/path/to/gdal-config
gdal (actually ogr) is used by the seeding utility to allow the seeding of tiles only intersecting a given polygon, e.g.
to preseed all the tiles of a given country.
geos (from 0.5 onwards) (optional)
===================================
--with-geos=/path/to/geos-config
along with gdal/ogr, geos is needed by the seeder to test for the intersection of tiles with geographical features.
pcre (optional)
===============
--with-pcre=/path/to/pcre/prefix
pcre (perl compatible regular expressions) can be used instead of posix regular expressions for validating WMS dimensions.
they are more powerfull than posix REs (and might be slower). you don't need this if you aren't planning on using WMS
dimension support with regex validation, or if your validation needs are covered by posix REs.
fastcgi support (optional)
==========================
mod-mapcache can run as a fastcgi executable. Note that the overhead of fastcgi is non-negligeable with respect to
the throughput you may obtain with a native apache module. Note that the fastcgi build is less tested, and may lag behind
compared to the apache module version on some minor details (most notably on error reporting, and cache-control header
generation).
--with-fastcgi=/path/to/fastcgi/prefix
give the location of the fastcgi libraries and headers.
Experimental options, use at your own risk
------------------------------------------
debug
=====
--enable-debug
enables some extra tests inside the code, and prints out many more debugging messages to the server logs. you should
probably not enable this unless you want to track down a problem happening inside mod-mapcache.
file locking
============
--with-lock-mechanism=file|semaphore
mod-mapcache needs to keep a cross-process and cross-thread lock on tiles so that requests for tiles of a same metatile
don't end up becoming multiple requests for the same metatile on the wms server. The default mechanism "file" is highly
recommended unless you know what you are doing.
This can be configured in two different ways in mod-mapcache, each with their advantage and inconvenience:
* file : mod-mapcache will use a file to signal other rendering threads that the given metatile is being rendered by the
wms source. (the location of these files is configurable with the <lock_dir> configuration directive). In the case of
threaded mpm, this has the inconvenience that we cannot be signaled by the operating system that this file has been
deleted, and thus must resort to sleeping every .5 sec and checking if the file still exists until the file is deleted.
This isn't very efficient, but should not be problematic in practice as this loop only happens if the tile wasn't
already in the cache, i.e. at most once per tile for the whole lifetime of the cache.
* semaphore : mod-mapcache can use posix semaphores for waiting on tile rendering. This method has the inconvenience
that if a rendering thread crashes (or more likely is killed by the system administrator while waiting for the wms
source to finish rendering), the semaphore lives on in the operating system and will prevent all accesses to the
tile until the sempahore is manually deleted. As apache threads are locked while waiting for this semaphore that
will never be released, you might end up with loads of idle processes stacking up. (stuck semaphores on linux can
be discarded by deleteing the files of the form sem.x-x-x-gridname-tilesetname(...) that are located in /dev/shm/.
The "file" maechanism does not have this limitation, as stale lockfiles can be deleted upon server restart.
Win32 compilation instructions
------------------------------
TODO