O'Reilly logo

Web Mapping Illustrated by Tyler Mitchell

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Installing MapServer

MapServer runs on a variety of platforms, and the details for installing it vary depending on where you want to run it and how you want to integrate it with the rest of your system.


Many operating systems and processors can run MapServer successfully. A recent survey of MapServer application developers showed dozens of different implementations running on many processor speed and type combinations. Included in the survey results were the following operating systems:

  • Windows 2000, XP, 95

  • RedHat/SuSE/Debian/Mandrake Linux, Versions 6 through 9

  • Solaris

  • Mac OS X Panther

  • Vmware running Windows and Linux

  • FreeBSD

  • SCO Open Server


Reported processor speeds were as low as 120 MHz and as little as 64 MB of memory. Others use the latest processing and memory resources available. With the diversity and flexibility required to meet these cross-platform requirements many developers have found MapServer to be the only option for serving web-based maps.

Acquiring MapServer Binaries

Many documents or how-tos include information on compiling MapServer, which can lead you to assume that compiling MapServer from source code is required. For most users it isn’t required. Acquiring binaries refers to the process of downloading executables and libraries that are ready to run on your operating system of choice, without compiling from source code.

Windows versions

MapServer application designers wanting to use Microsoft Windows to run MapServer can download standard Windows packages that include everything you need to get started. The packages include all the required MapServer programs zipped into a single file for download. Packages are available from a few locations, including the main MapServer web site (http://mapserver.gis.umn.edu/win32binaries.html), the MapTools.org site (http://dl.maptools.org/dl/), or from other users via mailing list discussions.

The MapTools.org web site has the easiest-to-use package and is highly recommended for inexperienced MapServer application developers using Windows. The package is called MapServer For Windows (MS4W for short) and is located at http://maptools.org/ms4w/.

MS4W was put together by DM Solutions Group (Ottawa, Canada). This company is involved in the development, implementation, and support of MapServer and related technologies. They provide this Windows package to help their users get up and running quickly.

The package is a single ZIP file containing everything needed to get started with MapServer—including an Apache web server. This requires no configuration! If you have shied away from toying with web servers, this is the package for you. To install MS4W, simply unzip the package file into the root of a drive (e.g. C:\ ). It should automatically create a set of subfolders under C:\MS4W\, including a folder called Apache within which the web server program resides.


The package can be moved to other locations on your filesystem, but this requires changing various web server settings.

To start the web server, run the Apache executable from C:\ms4w\apache\bin\apache.exe. This can be done from within Explorer and doesn’t have to be run from the command line. If you open your browser and go to http://localhost, you should see an MS4W welcome screen. This means that Apache is up and running. At this point you are ready to develop a MapServer application. The MS4W package contains all the libraries, programs, and configuration files you require. A summary of what MS4W contains is shown in Table 4-1. Using these files to create an application is discussed further in Chapter 10.

Table 4-1. Summary of components included in MapServer for Windows (MS4W)




Web server


Scripting language


MapServer CGI program


PHP/MapScript scripting libraries; see Chapter 14 for more on MapScript

proj.exe/cs2cs.exe, etc.

PROJ.4 projection utilities and libraries


MapServer command-line utilities


OGR command-line utilities

Linux binaries

An emerging project called Free Open Source Software GIS Suite (FGS) is available at http://maptools.org/fgs/. This project provides a packaging mechanism for all the required binaries, libraries, and other support files needed to run FGS applications. The initial version installs a minimal environment for Apache, PHP, and MapServer.

Linux GIS distributions

There are at least four Linux distributions that include MapServer and related applications.


This Debian-based distribution includes various GIS applications. See http://pkg-grass.alioth.debian.org/cgi-bin/wiki.pl.


This distribution includes MapServer, PostGIS, PHP, Python, Perl, and many other standard GNU/Linux applications. It’s based on Slackware Linux. See http://hostgis.com/linux.html.


This live CD distribution runs off a bootable CD-ROM. Includes MapServer, QGIS, and other GIS applications, including GRASS GIS. It’s based on Mandrake Linux. See http://rslultra.star.ait.ac.th/~yann/starcd/.


This bootable CD distribution includes a large number of major packages, including MapServer, PostGIS, Terraview, JUMP, QGIS, Thuban, Maplab, etc. See http://www.sourcepole.com/sources/software/gis-knoppix/.

Linux RPM versions

Linux RedHat Package Manager (RPM) files are available from several sites. While some of these have a comprehensive set of files, you may still need to get some support to help iron out dependencies. If you take all the packages from one site, you still might not have everything you need.


The LinGIS distribution of RPM files is packaged specifically for SuSE but will work on other Linux distributions as well. CD-ROM ISO images containing these RPM files are provided at http://lingis.org/.

Mapping Hacks GIS RPMs for Fedora Core

Locative Technologies (http://locative.us) has packages specifically for Fedora Core. They are available at http://mappinghacks.com/rpm/.

Debian Linux versions

There are several Debian Linux package repositories with MapServer available. They vary in features and dependencies. One repository is at http://agrogeomatic.educagri.fr/debian/.

Mac OS X

A somewhat outdated MapServer installation package is available at http://www.serverlogistics.com/mapserver.php. Most OS X users appear to compile MapServer and other packages from source code. A detailed explanation of that process is at http://webpages.charter.net/kyngchaos/macosx/mapservinstall.html.

Compiling MapServer Source Code

Any project claiming to be open source must provide access to the source code. In MapServer’s case, this allows you to modify the MapServer code to meet your specific needs. Even if you don’t plan to modify the source code, you may still want to compile directly from the source code. Some MapServer users find they need to compile their own version to include (or exclude) certain features. For example, there are a variety of data formats usually included in the binary distributions of MapServer. Quite often there are more formats than you require for a given application and you can remove support for those formats. If a certain format isn’t available by default, it can usually be added during the compilation process.

The compilation examples in this chapter are shown using Linux and open source compiling tools from the GNU project (see http://gnu.org). Tools and commands are run from the command line or shell console. Compiling for other operating systems varies depending on what tools are available. This section assumes that you are comfortable compiling code and have the appropriate tools available, including a C compiler such as gcc and configuration/building tools such as autoconf and automake.

Downloading sources

Current packages of source code are available from the MapServer web site download page http://mapserver.gis.umn.edu/dload.html. Those interested in the latest, greatest features may consider downloading one of the interim builds, which is a copy of the latest code from the developer code repository.


Source code download using Concurrent Versioning System (CVS) tools is available for those who want the absolute latest code. Access instructions are available at http://cvs.gis.umn.edu/cvs.html. CVS tracks changes to programming code and is used for managing the development of many software projects. For more information on CVS see http://www.gnu.org/software/cvs/.

Once the sources are downloaded, you need to unzip and untar them. This can be done in one step, as in the following command, which uses the GNU tar command:

    # tar -xzvf mapserver-4.4.0.tar.gz

This unzips the files into a new folder and creates a subfolder structure containing all the code. Once this is done, move into that directory and get ready to configure the build.

Configuring sources

You need to configure your options for compiling the MapServer program. This required step prepares the source code for compilation. The program file configure exists in the top level of the source tree, which you moved into after unzipping the sources. If you run the configure program without specifying any options, it uses a set of defaults. This may be all you need to do to get MapServer running. Several status messages, observations, and dependency checks are listed on the screen when configure is running. Running configure, as in Example 4-2, shows the results of the configuration process configure launches.

Example 4-2. Running configure and the resulting output from the configuration process
# ./configure
loading cache ./config.cache
checking for gcc... (cached) gcc
checking whether the C compiler (gcc  ) works... yes
checking whether the C compiler (gcc  ) is a cross-compiler... no
checking whether we are using GNU C... (cached) yes
checking whether gcc accepts -g... (cached) yes
checking for c++... (cached) c++
checking whether the C++ compiler (c++  ) works... yes
checking whether the C++ compiler (c++  ) is a cross-compiler... no
checking where PNG is installed...
checking for png_init_io in -lpng... no
        PNG (libpng) library cannot be found, possibly needed for GD
checking where libXpm is installed...
checking for XpmFreeXpmImage in -lXpm... no
        XPM (libXpm) library cannot be found, possibly needed for GD
checking where libiconv is installed...
checking for libiconv_open in -liconv... no
        libiconv library cannot be found, possibly needed for GD
checking for GD 2.0.12 or higher...
checking for gdImageSetAntiAliased in -lgd... yes
        using libgd 2.0.12 (or higher) from system libs
              (-L/usr/lib -lgd -ljpeg -lfreetype  -lz  ).
checking whether we should include PROJ.4 support...
        PROJ.4 support not requested.
checking whether we should include thread safe support...
        thread safe support disabled.
checking whether we should include ESRI SDE support...
        ESRI SDE support not requested.
checking whether we should compile in MPATROL support...
        MPATROL support not requested.
checking whether we should include OGR support...
        OGR support not requested.
checking if GDAL support requested... no
checking if PostGIS support requested... no
checking if MyGIS support requested... no
checking if OracleSpatial support requested... no
checking if MING/Flash support requested... no
checking whether we should include WMS Server support...
        OGC WMS Compatibility not enabled (PROJ.4 is required for WMS).
checking whether we should include WFS Server support...
        OGC WFS Server support not requested.
checking whether we shou install/erase scriptlets from  package(s)
ld include WMS Client Connections support...
        OGC WMS Client Connections not enabled (PROJ.4 and libcurl required).
checking whether we should include WFS Client Connections support...
        OGC WFS Client Connections not enabled (PROJ.4, libcurl and OGR required).
updating cache ./config.cache
creating ./config.status
creating Makefile

There are several things to note in the Example 4-2 output from the configure command. First, it checks to see if you have all the tools required to compile the source code. If you don’t, for example, have a C compiler, it will bail out on you and complain, as in Example 4-3.

Example 4-3. Configure fails when a C compiler can’t be found
loading cache ./config.cache
checking for gcc... (cached) gcc
checking whether the C compiler (gcc  ) works... no
configure: error: installation or configuration problem:
                   C compiler cannot create executables.

That’s good to know. After all, there is no sense continuing to prepare if you’ll get stuck later on.

configure checks on your system for various graphics libraries such PNG and GD and tests them out. If they are available, configure requests to use them during the compilation process.

Here’s the typical error message you receive when a set of libraries can’t be found:

    PNG (libpng) library cannot be found, possibly needed for GD

This is important to know, especially if you plan to use PNG image formats instead of GIF files in your maps. What you don’t see in the example is that it also checks for GIF and JPEG files. These can be used in place of PNG.

Next, configure checks for requests to build in support for various data formats and supporting applications. It helps to know what each format is. If configure can’t find them, they won’t be supported by your final MapServer program. Some may appear unimportant, unless you know what they are. The following example shows one such notice:

    PROJ.4 support not requested.

This notice isn’t good if you plan to use data that is projected into different coordinate systems. MapServer can take data in different coordinate systems and reproject them into a common system for the final map. You likely want to request PROJ.4 support, which means you also need to have the PROJ.4 files installed on your system. Enabling support for optional libraries, such as PROJ.4, is discussed later in this chapter.

Other format support statements are a bit more obvious, as seen in Example 4-4.

Example 4-4. Configure results from checking for requests to include various database formats
ESRI SDE support not requested.
checking if PostGIS support requested... no
checking if MyGIS support requested... no
checking if OracleSpatial support requested... no

These are all the checks for whether database support has been requested. None are selected by default, and are used only if the options are chosen. You’ll see more on configuration options in the next section.

Other important options not included by default include GDAL, OGR, and OGC specifications. The average user will appreciate having GDAL and OGR support. The utility of the OGC WMS/WFS client and server support options are for more advanced applications and have more advanced dependencies.

The configure process ends successfully by saying something like Example 4-5.

Example 4-5. A successful completion of the configuration process
updating cache ./config.cache
creating ./config.status
creating Makefile

You will notice that the last step is creating the Makefile. This file contains all the information for the make command to compile the sources (and link in the appropriate libraries, etc). This process is discussed in more detail later. If you are compiling from source code, I assume you aren’t afraid to run configure. The output appears somewhat cryptic to the average user. If you have a problem that is critical, the process usually quits and leaves its last observation for you to read. Understanding the output is necessary only when you have a problem.

In Example 4-3, configure couldn’t find the C compiler; it stopped right there and said there was a problem testing gcc (the GNU Compiler Collection typically used on Linux operating systems for compiling program code). If the message you see doesn’t make sense to you, don’t despair. The last few lines of the output are often all you need to get help from the mailing list (support references are at end of this chapter). The output from configure, however cryptic it may appear, will probably mean something to somebody.

configure options

Now that you’ve seen some examples of deciphering the output from configure, it is time to consider some of the options you can use with the configure command. Options are specified by adding parameters to the end of the configure command. This is done by using two dashes and a parameter name and value such as —with-sde after the configure command. To determine what options are available, you run configure with the —help parameter, as shown in the following code:

    # ./configure --help  | more

There are four sections to the configure help listing:

  • Configuration

  • Directory and filenames

  • Host type

  • Features and packages

The average user is interested only in the options under “Features and packages,” as shown in Example 4-6. The first few lines under this section show the syntax to use, then list the available MapServer-specific options.

Example 4-6. Listing of configuration options for features and packages
--with-jpeg[=DIR]       Include JPEG support (DIR is LibJPEG's install dir).
--with-freetype=DIR     GD: Specify where FreeType 2.x is installed
                          (DIR is path to freetype-config program or install dir).
--with-zlib=DIR GD: Specify where zlib is installed (DIR is path to zlib install dir).
--with-png=DIR GD: Specify where PNG is installed (DIR is path to PNG install dir).
--with-xpm=DIR  GD: Specify where libXpm is installed (DIR it the libXpm install prefix).
--with-libiconv=DIR     GD: Specify where libiconv is installed
                          (DIR is path to libiconv install dir).
--with-gd[=[static,]DIR] Specify which version of GD to use (DIR is GD's install dir).
--with-pdf[=DIR]        Include PDF support (DIR is PDFlib's install dir).
--with-tiff[=DIR]       Include TIFF support (DIR is LibTIFF's install dir).
--with-eppl             Include EPPL7 support.
--with-proj[=DIR]       Include PROJ.4 support (DIR is PROJ.4's install dir).
--with-threads[=linkopt]Include thread safe support
--with-sde[=DIR]        Include ESRI SDE support (DIR is SDE's install dir).
--with-sde-version[=VERSION NUMBER]  Set ESRI SDE version number (Default is 80).
--with-mpatrol[=DIR]    Include MPATROL support (DIR is MPATROL's install dir).
--with-ogr[=PATH]       Include OGR support (PATH is path to gdal-config).
--with-gdal[=PATH]      Include GDAL support (PATH is path to gdal-config)
--with-postgis[=ARG]    Include PostGIS Support (ARG=yes/path to pg_config)
--with-mygis[=ARG]      Include MyGIS Support (ARG=yes/path to my_config)
--with-oraclespatial[=ARG] Include OracleSpatial Support (ARG=yes/path to Oracle home)
--with-ming[=DIR]       Include MING/Flash Support (DIR=path to Ming
--with-wfs              Enable OGC WFS Server Support (OGR+PROJ4 required).
--with-wmsclient        Enable OGC WMS Client Connections (PROJ4 and libcurl
--with-wfsclient        Enable OGC WFS Client Connections (PROJ4, libcurl and
                          OGR required).
--with-curl-config=PATH Specify path to curl-config.
--with-httpd            Specify path to 'httpd' executable.
--enable-ignore-missing-data   Ignore missing data file errors at runtime
                                 (enabled by default).
--enable-debug          Include -g in CFLAGS for debugging and enable
                        msDebug() output to stderr (i.e. server log file).
--with-php=DIR          Specify directory where PHP4 source tree is
                        installed. Required in order to compile the
                        PHP/MapScript module.

That’s a lot of options! If they look confusing, don’t fret. The ones that concern you most will most likely be apparent; you can probably ignore or disable the rest. Each option can’t be discussed here, so it will take some guesswork on your part. Each item is for enabling data format support or output formats you want to use. If you know what formats you need to use, you should make note of them. Likewise, if you know what formats you want to output the data, find them on this list. If you don’t care what image format the output is in, the default will probably suffice.

Many parameters can be specified with either an —enable or —disable option, which is equivalent to —with and —without, respectively. In order to simplify the above list, I haven’t shown all the disable options.

Most parameters will seem straightforward after a simple introduction. There are books that specialize in teaching source code compiling techniques, so only the bare minimum required to configure and compile MapServer is presented here. For much more depth on the configuration and compilation process, consider reading:

There are essentially two different ways to specify parameters:

  • specifying —enable-x or —with-x

  • adding a value to the end, such as —enable-x=y

The first usage is quite simple: if you want to enable a feature, add a parameter that specifies to enable it with x being the name of the feature, as shown in the help listing.

The following example shows how to direct configure to find the library or programs needed to add in JPEG image support; configure will complain if it doesn’t find what it needs.

                  ./configure --with-jpeg

If the required libraries aren’t found, in this case the JPEG libraries, you may need to use the second method of specifying the parameter. Notice that the help listing (Example 4-6) said:


The [=DIR] is an optional part of the parameter. Any parameters enclosed in the square brackets aren’t always required. What configure wants is some help finding the JPEG library-related files. You have to tell it where they are installed. When in doubt as to what configure wants to know, look back at the help listing (Example 4-6). Beside the JPEG option it says:

    Include JPEG support (DIR is LibJPEG's install dir)

So if you know where the LibJPEG files are located, you can explicitly tell configure to go look there.


Finding dependency locations is discussed in the next section.

Sometimes configure needs the include and lib files associated with the library. This is the case with the LibJPEG configuration. You must point to the root folder in which the libraries have been installed; it has the include and lib folders, including LibJPEG files. This can also be the source directory in which you compiled LibJPEG before installing it. For example, I compile all my source code in /home/tyler/src/. If I compile LibJPEG from source in /home/tyler/src/jpeg, I can point configure to that location instead.

In my case, libJPEG was installed into /usr/lib and therefore I’d run configure as in the following example:

    ./configure --with-jpeg=/usr

Because this is a fairly common location for these libraries, I probably didn’t need to specify the location; configure probably would have searched there anyway. However, if you’ve installed the libraries in an uncommon location (e.g., in a personal folder for testing MapServer), this option is important to understand.

Not all parameter options want a folder. Some require a [=PATH] or [=ARG] value to be specified. For example with the GDAL option as seen earlier (Example 4-6):

    --with-gdal[=PATH] Include GDAL support (PATH is path to gdal-config)

Reading the description on the right is critical to specifying this parameter properly. It doesn’t just want the folder that gdal-config is located in, it wants the full path to the gdal-config file. Because this path argument is optional, it looks for the file in a few obvious places. If you have it tucked away somewhere strange, you will need to be more specific and put the entire path into the parameter, as in the following code. After deciding what options you want to include, you string them into one long command and let configure do its work.

                  ./configure --with-jpeg --with-png --with-ogr --with-gdal=/usr/local/bin/gdal-config

You need to be explicit with DIR and PATH arguments only when necessary. When running configure after selecting the options, review the output text configure prints to your screen and find the lines that pertain specifically to the options you chose. If you see that an item doesn’t check out properly, as in the following example, you’ve done something wrong.

    checking whether we should include OGR support...
    ./configure: line 1: /usr/local/bin/gdal-config: No such file or directory

In this case, a location for gdal-config was specified, but the file didn’t exist because GDAL wasn’t installed (this is a separate, optional process described further in Chapter 4). Sometimes it keeps looking around and finds the file, despite the wrong PATH argument, but don’t bet on it. If you get a bunch of errors, you can reenter your configure command and change the parameters until they work.


Perhaps one of MapServer’s greatest strengths is its ability to draw upon already existing libraries. The developers have focused on supporting a small central core of requirements while allowing increased functionality by relying on external libraries rather than building more dependencies into the basic project. The result is a powerful product that can be extended to include other functionality without major changes to the core program.

For those who need just the bare-bone basics for their application, there are very few external dependencies. On many systems, the required libraries or external programs may already be installed.

Potential dependencies include:

  • Image format libraries: JPEG, PNG, XPM, LIBICONV

  • Graphic formatting/add-on libraries: GD, FREETYPE, PDF, MING

  • Data format/application support libraries: TIFF, EPPL, SDE, MPATROL, OGR, GDAL, POSTGIS, MYGIS, ORACLESPATIAL

  • Coordinate Projection library: PROJ.4

  • Web services options: WMS, WFS, CURL, HTTPD, PHP

How do you know which external libraries you need? Usually the configure and make programs will notify you of any missing libraries.

Understanding the role that key supporting libraries play can help make the messages (from configure and make) less cryptic. It can also help you plan ahead to prepare the libraries you might need but don’t already have.

For the most basic MapServer, the only documented requirement is access to the GD image creation library (from http://www.boutell.com/gd/). This library is used to create the map images.


When I saw my first MapServer application, I was blown away by its ability to create an image so quickly from fairly complex vector and raster data. This was thanks to the GD library . GD is an image processing and creation environment, and a core requirement of MapServer.

The GD library is so critical to MapServer that if you try to disable GD or don’t have it available, configure won’t let you continue, as shown in Example 4-7.

Example 4-7. Trying to disable GD support during configuration
# ./configure --without-gd
checking for GD 2.0.12 or higher...
configure: error: GD library cannot be disabled

Aside from GD, there are no other basic requirements for MapServer. However, for GD to produce usable images for MapServer, it requires some sort of image library support. In order for GD to be properly installed, you need a PNG or JPEG library. You may already have one or more of these on your system.

MapServer can produce output images in a variety of formats. Perhaps the best known are JPEG, GIF, and PNG formats. Support libraries for the formats you want to use must be available to GD.

Most modern Linux platforms have Version 2 of GD installed; it’s called GD2. MapServer 4.4 requires GD2 libraries. You will also need to have development files for GD2, which include supporting files for other programs compiling in GD2 support. If installing from RPMs, the gd2-devel package will give you the development files. To check if a package is already installed, run:

    rpm -qa | grep <name of package>

For example, to see if gd is installed, you can run:

    rpm -qa | grep gd

Installed packages are listed. No response means no RPM packages are installed. Older versions of Linux, and other operating systems, won’t have GD2. In this case, you still need development libraries for the version of GD you are running. In some cases, this may limit you to using pre-4.4 versions of MapServer.


If PNG support is desired, ZLIB libraries are also required. In order to install GD, you will most likely need to have PNG/ZLIB, JPEG, and FreeType libraries available.

The most basic version you can compile will likely find PNG, JPEG, WBMP (Windows bitmap) and FREETYPE (TrueType font) supporting libraries already on your system and automatically build them in.

If you run configure and explicitly use —without for every option, configure still finds a few libraries and incorporates them (despite the request not to). What you are left with is a setup that will read only two types of files: JPEG images and ESRI shapefile-format vector data files. This minimalistic setup can output into image types PNG, JPEG, and WBMP and, optionally, render TrueType Fonts (TTF) as labels on the map image.

What this leaves you with is very basic, but it will get you started testing the basics of MapServer. Many people just run ./configure without any options and see if there are any obvious problems. In some cases, this is enough for a simple MapServer setup.

Making a compile

When the configuration process is complete, you are ready to start compiling the application. Depending on the options to be included, this process can take quite a while to complete. The compilation process begins by running the make command as shown in Example 4-8.

After running make, you will see numerous commands and information scrolling up the screen. When the compilation process is complete, there won’t be a message; you are just returned to the command prompt. Example 4-8 shows some sample output from the beginning and end of the make process.

Example 4-8. Results of running the make command to start compiling
# make
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include maptemplate.c -o maptemplate.o
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include mapbits.c -o mapbits.o

[ *.........80+ lines removed...........* ]

   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include sortshp.o
   -L. -lmap -lgd -L/usr/lib -lgd -ljpeg -lfreetype -lz -ltiff -ljpeg
   -lfreetype -lz -ljpeg -lm -lstdc++ -o sortshp
touch mapscriptvars
pwd > mapscriptvars
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT >> mapscriptvars
echo -I.  -I/usr/include >> mapscriptvars
echo  -L. -lmap -lgd -L/usr/lib -lgd -ljpeg -lfreetype -lz -ltiff -ljpeg
   -lfreetype -lz -ljpeg -lm -lstdc++ >> mapscriptvars
echo   >> mapscriptvars
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include tile4ms.c -o tile4ms.o
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include tile4ms.o
   -L. -lmap -lgd -L/usr/lib -lgd -ljpeg -lfreetype -lz -ltiff -ljpeg
   -lfreetype -lz -ljpeg -lm -lstdc++ -o tile4ms

You may see various warning messages in the output listing. They can be ignored, as long as you don’t get an error that kicks you out of the process.

If you have compiled programs before, you will be tempted to run make install next. That’s fine, but ineffective. There is no install process for MapServer; you simply copy the mapserv executable into your web server’s cgi-bin directory. If you run make install, you get further instructions as a reminder of what to do, as in Example 4-9.

Example 4-9. The results of running make install
# make install
***** MapServer Installation *****
To install MapServer, copy the 'mapserv' file to your web server's cgi-bin
If you use MapScript then see the documentation for your specific MapScript
version for installation instructions.

The make command has produced the mapserv executable file this message is referring to. If you don’t have a file called mapserv after the make command is run, it did not complete properly. The message also refers to MapScript. MapScript is an advanced scripting option for MapServer that’s discussed further in Chapter 14.

You can test the mapserv executable by running it with the -v parameter, as in Example 4-10. This lists the version and optional parameters that are compiled into MapServer.

Example 4-10. Requesting the version and formats supported by the MapServer CGI program
# ./mapserv -v

This example shows the various input and output data format options selected during the configuration process. You can run mapserv without the -v parameter, but it will remind you, as in Example 4-11, that it isn’t meant to be run as a standalone program.

Example 4-11. Running mapserv from the command line without any options
# ./mapserv
This script can only be used to decode form results and
should be initiated as a CGI process via a httpd server.

If you call the mapserv program without any parameters from a web page, you get a slightly different message:

    No query information to decode. QUERY_STRING is set, but empty.

This can become a useful way to make sure mapserv is installed properly; it’s discussed in more detail in Chapter 11.

Other programs are created at the same time as mapserv. These include scalebar, shp2img, shptree, tile4ms, and more; they are discussed further in Chapter 10.


How-to documents for compiling MapServer are available on its web site http://mapserver.gis.umn.edu/doc/.


Another strength of MapServer is its ability to run multiple versions that include different abilities, all on the same computer. One application could be set up to use a more stable version while another may use a recent test version. This flexibility is possible because the mapserv program runs as a CGI application through a web server. Any MapServer web application can call a specific version of the mapserv executable. You will learn more about this in Chapter 11.

The typical method of installation is to copy the mapserv file into a web server’s cgi-bin folder. If the file is in a folder that the web server can execute the file from (for example, the cgi-bin folder), that’s all that is required to install the CGI version of MapServer. More advanced configurations will have more dependencies, but ultimately the main installation step is to copy the mapserv file into the cgi-bin folder, or one with equivalent properties.

RPM packages do some of this work for you, but you need to make sure you know where the mapserv file is put. For example, the RPM may try to put the mapserv file in /var/www/cgi-bin by default, but you may need it somewhere else. On SuSE Linux running Apache, it should go in /srv/www/cgi-bin.

If you plan to install MapServer from an RPM package, it is wise to get a listing of the files and locations the RPM creates. This can be done using the RPM package query and list functions as shown in Example 4-12.

Example 4-12. Listing the contents of the MapServer RPM package
# rpm -qpl mapserver-4.0.1-1.i386.rpm

Once installation is complete, mapserv can process CGI requests and return maps. This requires other parts of the overall MapServer framework to be set up, as discussed in Chapter 11.

A quick test of the install

You can run a basic test on MapServer by running the mapserv or mapserv.exe program. The simplest test you can do is from the command line. First, you open a command prompt, and change into, or at least find, the folder that contains mapserv, mapserv.exe, or mapserv_ xx where xx can be a version number such as 44 for mapserv Version 4.4. For MS4W, mapserv.exe is located in the c:\ms4w\apache\cgi-bin folder.

If you compile from source, mapserv is in the source code folder it was compiled in. If you install from an RPM binary, mapserv is in the default Apache web server folder. For example, on SuSE, it’s in /srv/www/cgi-bin, and on Fedora, it’s in /var/www/cgi-bin.

From the command prompt, execute the mapserv program. For example, on SuSE Linux, use the command:


With MS4W, use:


Either way, the output you get should look like:

    This script can only be used to decode form results and
    should be initiated as a CGI process via a httpd server.

Yes, this is an error message, but it confirms that you at least have a working version of the MapServer program. Congratulations—you are ready to start working with MapServer in Chapters 10 and 11.

If all the dependencies for MapServer aren’t available, you may get a different error message. Figure 4-4 shows an example of a Windows error message when a supporting library, GDAL for instance, can’t be found.

Dependency error message from MapServer on Windows
Figure 4-4. Dependency error message from MapServer on Windows

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required