INSTALL

Unix compilation instructions
-----------------------------

Mapcache now builds with cmake. It seems much happier if it can find apxs, which means you
might need apache2-prefork installed (on ubuntu apt-get install apache2-prefork-dev).

cd mapcache
mkdir build
cd build
cmake ..
# follow instructions below if missing a dependency
make
sudo make install

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>

Before you restart, copy the example mapcache.xml file to where you want it:

cp mapcache.xml /path/to/directory/mapcache.xml

(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 cmake script will try to locate them in default system locations, that can be
overriden or specified with -D switches. For example, if you don't want fcgi and
you get a message such as 'Could NOT find APR ', you can use a command such as: 
(assuming that apr is at /usr/local/apr)

cmake -DWITH_FCGI=0 -DCMAKE_PREFIX_PATH="/usr/local/apr;" ..



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). 
On Ubuntu, apt-get install apache2-prefork-dev might help

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.


enabling mod_mapcache on Ubuntu
===============================

Ubuntu has it's own method of invoking modules, using a 'load' file.
The conf files should be created in /etc/apache2/mods-available/, ie 

echo 'LoadModule mapcache_module /usr/lib/apache2/modules/mod_mapcache.so' > /etc/apache2/mods-available/mapcache.load

and then enable it: a2enmod mapcache

However, before you restart apache, you will need to make the lib (which is in 
/usr/local/lib) available, maybe by:

ln -s /usr/local/lib/libmapcache.so /usr/lib/libmapcache.so





Win32 compilation instructions
------------------------------
TODO