These instructions target a Debian/Ubuntu setup, but should apply with few
modifications to any Linux installation.

MapCache requires a number of library headers in order to compile correctly:

apache / apr / apr-util / apx2: these are included in the apache2-prefork-dev or
apache2-threaded-dev packages, depending on which Apache MPM you are running.
This package will pull in the necessary APR headers that you would have to
manually install if you are not buidling an Apache module (libaprutil1-dev
and libapr1-dev)

png: libpng12-dev

jpeg: libjpeg62-dev

curl: libcurl4-gnutls-dev

The following libraries are not required, but recommended:

pcre: libpcre3-dev. This will give you more powerful regular expression
syntax when creating validation expressions for dimensions

pixman: libpixman-1-dev. The pixel manipulation library is used for
scaling and alpha-compositing images. MapCache ships with some code to
perform these tasks, but Pixman is generally faster as it includes
code optimized for modern CPUs (SSE2, MMX, etc...)

The following libraries are not required, but needed to enable additional
functionalities:

fcgi: libfcgi-dev. Needed to build a FastCGI program if you don’t want to
run MapCache as an Apache module

The make install above installs the Apache module, but if you
specifically need to install only the Apache module you can do the following:

$ sudo make install-module
$ sudo ldconfig

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 ( e.g. /usr/local/httpd/conf/httpd.conf or
/etc/apache2/sites-available/default ):

LoadModule mapcache_module modules/mod_mapcache.so

Next, a MapCache configuration is mapped to the server URL with the following
snippet:

Run the configure command with the flag --add-module. This flag
must point to MapCache’s nginx child directory. Assuming that
MapServer source was cloned or un tarred into to /usr/local/src,
an example configure command for nginx would look like this:

$ ./configure --add-module=/usr/local/src/mapcache/nginx

Then build nginx:

$ make
$ sudo make install

Due to nginx’s non-blocking architecture, the MapCache nginx module does not
perform any operations that may lead to a worker process being blocked by a
long computation (i.e.: requesting a (meta)tile to be rendered if not in the
cache, proxying a request to an upstream WMS server, or waiting for a tile to
be rendered by another worker): It will instead issue a 404 error. This
behavior is essential so as not to occupy all nginx worker threads, thereby
preventing it from responding to all other incoming requests. While this isn’t
an issue for completely seeded tilesets, it implies that these kinds of
requests need to be proxied to another MapCache instance that does not suffer
from these starvation issues (i.e. either a FastCGI MapCache, or an internal
proxied Apache server). In this scenario, both the nginx MapCache instance and
the Apache/FastCGI MapCache instance should be running with the same
mapcache.xml configuration file.

MapCache supplies an nginx.conf in its nginx child directory. The conf
contains an example configuration to load MapCache. The most relevant part of
the configuration is the location directive that points the ^/mapcache URI
to the mapcache.xml path. You will need to change this path to point to
your own mapcache.xml in the MapCache source.

The basic configuration without any proxying (which will return 404 errors on
unseeded tile requests) is:

If proxying unseeded tile requests to a MapCache instance running on an Apache
server, we will proxy all 404 MapCache errors to a mapcache.apache.tld
server listening on port 8080, configured to respond to MapCache requests on
the /mapcache location.

If using FastCGI instances of MapCache, spawned with e.g. spawn-fcgi or
supervisord on port 9001 (make sure to enable FastCGI when building MapCache,
and to set the MAPCACHE_CONFIG_FILE environment variable before spawning):

Copy the relevant sections of nginx.conf from MapCache’s nginx
directory into nginx’s conf file (in this case
/usr/local/nginx/conf/nginx.conf). You should now have access to the demo
at http://myserver/mapcache/demo

A binary CGI/FastCGI is located in the mapcache/ subfolder, and is named “mapcache”.
Activating FastCGI for the MapCache program on your web server is not part of
these instructions; more details may be found on the FastCGI
page or on more general pages across the web.

The MapCache FastCGI program looks for its configuration file in the environment
variable called MAPCACHE_CONFIG_FILE, which must be set by the web server before
spawning the MapCache processes.

Depending on which packages are available in the default locations of your system,
the “cmake ..” step will most probably have failed with messages indicating
missing dependencies (by default, MapCache has some of those). The error message
that CMake prints out should give you a rather good idea of what steps you should take
next, depending on whether the failed dependency is a feature you require in your build.

mod_mapcache requires Apache, libcurl, libjpeg and libpng development headers.
The CMake script will try to locate them in default system locations, but these locations can be
overridden or specified with -D switches. For example, if 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 -DCMAKE_PREFIX_PATH="/usr/local/apr;" ..

If you don’t want e.g. fcgi, you can disable the dependency by re-running CMake with -DWITH_DEPENDENCY=0, e.g.

Here is a list of supported options that can be enabled/disabled at build.

option(WITH_PIXMAN"Use Pixman for SSE optimized image manipulations"ON)option(WITH_SQLITE"Use SQLite as a cache backend"ON)option(WITH_BERKELEY_DB"Use Berkeley DB as a cache backend"OFF)option(WITH_MEMCACHE"Use memcache as a cache backend (requires recent apr-util)"OFF)option(WITH_TIFF"Use TIFFs as a cache backend"OFF)option(WITH_TIFF_WRITE_SUPPORT"Enable (experimental) support for writable TIFF cache backends"OFF)option(WITH_GEOTIFF"Allow GeoTIFF metadata creation for TIFF cache backends"OFF)option(WITH_PCRE"Use PCRE for regex tests"OFF)option(WITH_MAPSERVER"Enable (experimental) support for the MapServer library"OFF)option(WITH_GEOS"Choose whether GEOS geometry operations support should be built in"ON)option(WITH_OGR"Choose whether OGR/GDAL input vector support should be built in"ON)option(WITH_CGI"Choose whether CGI executable should be built"ON)option(WITH_FCGI"Choose whether CGI executable should support FastCGI"ON)option(WITH_VERSION_STRING"Show MapCache in server version string"ON)option(WITH_APACHE"Build Apache Module"ON)

Pixman (recommended, from 0.5 onwards)

-DWITH_PIXMAN=[0|1]

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 (MMX,
SSE2, etc.) to speed up blending and resampling operations. If the Pixman
library is not found, MapCache will fall back to internal pixel operations
that are slower.

SQLite (optional, from 0.5 onwards)

-DWITH_SQLITE=[0|1]

SQLite is used to enable the SQLite and MBTiles cache backend. Version 3.5.0
or newer is required.

GDAL (optional, from 0.4 onwards, also requires geos)

-DWITH_OGR=[0|1]

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 (optional, from 0.5 onwards)

-DWITH_GEOS=[0|1]

Along with GDAL/OGR, GEOS is needed by the seeder to test for the intersection
of tiles with geographical features. A sufficiently recent version of GEOS (with
support for prepared geometries) is required (but not enforced by the configure
script, so you’ll end up with compilation errors if a too old GEOS version is
used).

PCRE (optional)

-DWITH_PCRE=[0|1]

PCRE (Perl Compatible Regular Expressions) can be used instead of POSIX regular
expressions for validating WMS dimensions. They are more powerful 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.

MapCache can run as a FastCGI executable. Note that the overhead of FastCGI
is non-negligible with respect to the throughput you may obtain with a native
Apache module. The FastCGI build is less tested, and may lag behind
the Apache module version on some minor details. YMMV.

TIFF read/write Cache Support (optional)

Use TIFFs as a cache backend (READONLY) :

-DWITH_TIFF=[0|1]

TIFF write support (for creating new TIFF files and adding tiles to existing
TIFF files) is still experimental and disabled by default. There is a risk of
ending up with corrupt TIFF files if they are placed on a filesystem that does
not honor file locking, as in that case multiple processes might end up writing
to the same file. File locking across concurrent threads is also problematic,
although MapCache tries to detect this situation and apply sufficient locking
workarounds. To stay on the safe side, write support should for now only be
enabled on local filesystems, with a prefork MPM or FastCGI MapCache install.

-DWITH_TIFF_WRITE_SUPPORT=[0|1]

When writing TIFF files, MapCache can also optionally add georeferencing
information if compiled with libtiff support. GeoTiff writing does not
produce the full tags needed for defining which preojection the grid is
in, but will only produce those defining the pixel scale and the tiepoints
(i.e. the equivalent information found in the accompanying .tfw files).

You can disable the Apache module building if you only plan on using the
FastCGI executable or the seeder.

-DWITH_APACHE=[0|1]

MapCache adds itself to the version string reported by the Apache server. This
can be disabled with:

-DWITH_VERSION_STRING=[0|1]

Native MapServer Mode (experimental options)

MapCache is by default not linked to MapServer in any way, and communicates
through the WMS protocol only. For improved performance, it is possible
to directly use the MapServer C library and avoid an HTTP request and an image
compression/decompression. This integration is still experimental and should
be used cautiously.

-DWITH_MAPSERVER=[0|1]

This will use the libmapserver.so from MapServer’s install directory. MapServer
itself should be compiled with thread-safety enabled, unless you plan to use the
prefork MPM or FastCGI, and you do not plan to use the seeder. For thread
safety on the MapServer side, you might want to have a look at tickets #4041
and #4044.

Debug Mode (work in progress)

Note

Since the CMake migration, this has to be done.

It 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 MapCache.

The following instructions are outdated. Windows builds are now handled
identically to the Unix ones with CMake.

These instructions target a Windows 7 setup with an Apache httpd compiled from
source. The Apache MapCache module has been successfully built with with
Microsoft Visual Studio C++ versions 2003, 2008 and 2010.