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
Mac OS X Panther
Vmware running Windows and Linux
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.
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.
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)
MapServer CGI program
PHP/MapScript scripting libraries; see Chapter 14 for more on MapScript
PROJ.4 projection utilities and libraries
MapServer command-line utilities
OGR command-line utilities
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.
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 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/.
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/.
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.
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
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 -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.
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
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
configure is running.
configure, as in Example 4-2, shows the
results of the configuration process
Example 4-2. Running configure and the resulting output from the configuration process
./configureloading 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
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.
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.
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
In Example 4-3,
configure couldn't find the C
compiler; it stopped right there and said there was a problem
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.
Now that you've seen some examples of deciphering the
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
./configure --help | more
There are four sections to the
configure help listing:
Directory and filenames
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 directory) --with-wfs Enable OGC WFS Server Support (OGR+PROJ4 required). --with-wmsclient Enable OGC WMS Client Connections (PROJ4 and libcurl required). --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
—disable option, which is equivalent to
—without, respectively. In order to
simplify the above list, I haven't shown all the disable
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:
adding a value to the end, such as
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.
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:
[=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
configure to go
the include and lib files associated with the library.
This is the case with the
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,
installed into /usr/lib and therefore I'd run
configure as in the following
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
[=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 --with-postgis
You need to be explicit with
PATH arguments only when necessary. When
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
How do you know which external libraries you need? Usually the
make programs will notify you of any
Understanding the role that key supporting libraries play can
help make the messages (from
make) less cryptic. It can also help you
plan ahead to prepare the libraries you might need but don't already
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
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
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
—without for every
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
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.
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.
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
Example 4-8. Results of running the make command to start compiling
makegcc -c -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include maptemplate.c -o maptemplate.o gcc -c -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include mapbits.c -o mapbits.o [ *.........80+ lines removed...........* ] gcc -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG -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 echo -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG -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 gcc -c -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include tile4ms.c -o tile4ms.o gcc -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG -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
install next. That's fine, but
ineffective. There is no
process for MapServer; you simply copy the
mapserv executable into your web server's
cgi-bin directory. If you run
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 directory. If you use MapScript then see the documentation for your specific MapScript version for installation instructions.
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
You can test the
executable by running it with the
-v parameter, as in Example 4-10. This lists the
version and optional parameters that are compiled into
Example 4-10. Requesting the version and formats supported by the MapServer CGI program
./mapserv -vMapServer version 4.4.0 OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP SUPPORTS=FREETYPE INPUT=TIFF INPUT=JPEG INPUT=SHAPEFILE
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
./mapservThis 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
program without any parameters from a web page, you get a slightly
http://localhost/cgi-bin/mapserv 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
tile4ms, and more; they are discussed
further in Chapter
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
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/usr/bin/shp2img /usr/bin/shptree /usr/bin/sortshp /usr/bin/tile4ms /var/www/cgi-bin/mapserv
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.
You can run a basic test on MapServer by running the
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
xx can be a version number such as
mapserv Version 4.4. For MS4W,
mapserv.exe is located in the
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
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.
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.