Pericles S. Nacionales
University of Minnesota
Conservation Biology Program
pnaciona@gis.umn.edu
This HOWTO provides a set of procedures for compiling and installing MapServer on Win32 platforms using the Cygwin environment.
Last Updated: 16 November, 2001
If you are familiar with Cygwin and already know about MapServer, you may skip this section and the next, and proceed directly to "Example MapServer configuration". If you are just getting started with Cygwin and MapServer, you should begin here. If you've never heard of MapServer before, you're in the wrong place; go here first. For all others, read on.
The University of Minnesota's MapServer is an open-source software for building web-enabled mapping applications. It serves a growing community of GIS and "spatially-minded" folks who use the internet as a way to present and deliver spatial data. While MapServer can be configured and compiled on several operating systems, this document focuses on compiling and installing MapServer on the Cygwin environment which runs on top of Win32 operating systems.
Because of Cygwin's UNIX-like environment and the collection of GNU tools that come with it, knowledge of the UNIX shell environment will be helpful. If you are not familiar with the bash shell, I would suggest looking at other alternatives to compiling MapServer on Windows—one such alternative is the Microsoft Visual C/C++ (MSVC). There is a HOW-TO document for compiling MapServer with MSVC. For those who are not so knowledgeable with UNIX shell but still would like to use Cygwin to compile MapServer, I'll attempt to provide an easy to follow steps in compiling. Aside from familiarity with UNIX shell environment, those who wish to compile MapServer under Cygwin should also be familiar with the "build" environment--particularly the autoconf and GNU make.
For installation and application-development purposes, basic knowledge of web server configuration and the CGI environment is required. The MapServer binary compiled under Cygwin has been known to run on Apache web server and that's the server I will use in this document.
Note: Cygwin and the GNU tools that come with it are continually being updated. I was using Cygwin with the DLL version 1.3.3 when this HOWTO was originally written. While I hope that you won't run into compatibility problems with the different Cygwin versions, I can't make any guarantees. I would recommend upgrading to the latest version if you are running older versions of the DLL (before 1.3.x).
MapServer source code can be downloaded as a package from http://mapserver.gis.umn.edu/dload.html. Download the latest version of MapServer (3.5) or the latest nightly-build source code.
Additional software packages are needed for input and output data support for MapServer. There are a few packages (libraries) that MapServer has to have in order to work, and a few more that can provide additional capabilities but are not required. Some of these packages come with Cygwin and don't need to be compiled. For those that didn't come with Cygwin, download and compile them before compiling MapServer. Here are some of the required and optional libraries that can be compiled with MapServer:
If you want to use any of these libraries, please click on the links provided. Please read more about the software before navigating to its download page. When you download the software, place them into one directory. This is the directory you will use to compile MapServer and the libraries.
Tip: Create a "projects" subdirectory under the /usr/src directory. In Cygwin, use the following command: "mkdir /usr/src/projects". If you use Windows Explorer, create the projects folder under C:\Cygwin\usr\src, or wherever you installed Cygwin. You can then put all your downloaded source codes under this directory.
Cygwin comes with GD, LibPNG, Zlib, LibTIFF, and LibJPEG libraries. To compile MapServer with PNG output and Shapefiles and TIFF/JPEG input, you are ready to proceed. However, if you want GIF output and isn't affected by LZW patent infringement, I suggest downloading a patched GD library from http://www.rime.com.au/gd/.
At this point I will provide an example that users can follow and build on. The MapServer CGI program I will compile will have input support for ESRI shapefiles, as well as TIF and JPEG images. No special libraries are needed because MapServer has built-in Shapelib support and TIFF and JPEG libraries come with Cygwin. I will also include Proj.4 support so that I have the option of on-the-fly reprojection of my data layers. By having Proj.4, I can make my MapServer OGC-WMS server compliant. I happen to like purty fonts so I will also compile MapServer with Freetype 1.3 (because I have problems with Freetype2 :). Since Cygwin already comes with GD 1.8.4, I have the option of using that and have PNG or JPEG images as my output. However, many people still like to use GIF images so I will download the "patched" GD library with automake support (because it's so much easier with automake) from http://www.rime.com.au/gd. Please be aware of potential patent infringement here.
So, download the "patched gd library with GIF and Automake support" from http://www.rime.com.au/gd to /usr/src/projects. Then unpack the package using Cygwin. Here's the command to do so: "tar -xzvf gd-1.8.4amgif.tar.gz" You should end up with a subdirectory called gd-1.8.4 under /usr/src/projects. You may delete the source after unpacking ("rm gd-1.8.4amgif.tar.gz").
Download the Freetype 1.3 source from http://prdownloads.sourceforge.net/freetype/freetype-1.3.1.tar.gz and unpack like so: tar -xzvf freetype-1.3.1.tar.gz. You may delete the source after unpacking.
Download the Proj.4 source from ftp://ftp.remotesensing.org/pub/proj/proj-4.4.4.tar.gz and unpack like so: tar -xzvf proj-4.4.4.tar.gz. After unpacking, download proj-nad27-1.1.tar.gz from ftp://ftp.remotesensing.org/pub/proj to /usr/src/projects/proj-4.4.4/nad (C:\Cygwin\usr\src\proj-4.4.4\nad). change directory to proj-4.4.4/nad and unpack what you just downloaded. Delete the source after unpacking.
Download the MapServer source code at http://mapserver.gis.umn.edu/dist/nightly.tar.gz and unpack like so: tar -xzvf nightly.tar.gz. This will create a directory called mapserver. You should now have a directory tree structure like this:
/usr/src/projects/ freetype/ gd-1.8.4/ proj-4.4.4/ mapserver/
One last thing... Download Regex-0.12 from ftp://ftp.gnu.org/pub/gnu/regex/. While Cygwin comes with regex, that version doesn't work with MapServer somehow. I worked around it by compiling support for this older regex. Unpack the file inside the mapserver directory (from /usr/src/projects/mapserver) like so: "tar -xzvf regex-012.tar.gz". Your new regex subdirectory should be "/usr/src/projects/mapserver/regex-0.12". You are now ready to compile MapServer and the supporting libraries.
Before you can actually compile MapServer, you need to compile all the supporting libraries. This example calls for the patched gd-1.8.4, freetype, and proj.4 libraries. The steps in compiling and installing these libraries are similar to each other but there is order in what should be compiled first. By this I mean that some libraries "depend" on other libraries, much like MapServer depends on these libraries. In the case of GD, you can compile it as is. However, since I need freetype support in MapServer, I need to compile this support into gd. So I will first compile and install freetype before compiling GD. Proj.4 doesn't have any dependencies so we can compile it anytime. Well, I'll compile it first then.
Proj.4
To compile Proj.4, cd to proj-4.4.4 (assuming you are already on /usr/src/projects
under Cygwin bash shell). Type in "./configure". This will query your system
and generate a Makefile for you--one of the good things about the UNIX build
environment. When configure finishes generating the Makefile, simple type in
"make". When Proj.4 is compiled, type in "make install". This will install the
Proj.4 library, header and data files under the "/usr/local" directory. If you
want to, you can type "make clean" to delete the files created during the compilation
process. You are done with Proj.4.
Freetype
Since GD "depends" on Freetype for TrueType font support, you need to compile
it first. To do so, cd to the Freetype directory by typing in "cd ../freetype"
(assuming you are still in the Proj.4 directory. Otherwise, type in "/usr/src/projects/freetype").
Type in "./configure" and wait for it to finish. Now type in "cd lib" to go
to the lib directory. Type in "cp arch/unix/Makefile arch/win32/"--this will
copy your Makefile to the arch/win32 subdirectory. Edit "arch/win32/Makefile"
with your favorite text editor. Look for the lines:
VPATH = /cygdrive/d/projects/gnu/mapserver/freetype/lib/arch/unix/../.. srcdir = /cygdrive/d/projects/gnu/mapserver/freetype/lib/arch/unix/../..
and change them to these:
VPATH = /cygdrive/d/projects/gnu/mapserver/freetype/lib/arch/win32/../.. srcdir = /cygdrive/d/projects/gnu/mapserver/freetype/lib/arch/win32/../..
Don't forget to save the changes. Now back to the Cygwin console, type in "make -f arch/win32/Makefile" and wait for the compilation process to finish. When compile finishes type in "make -f arch/win32/Makefile install" to install the Freetype library and header files. If you want to, type in "make clean" to get rid of the intermediate files created in the compilation process. You are done with Freetype.
GD
You'll need to compile GD for two reasons--GIF and Freetype support. If you
don't need GIF support and don't mind using PNG graphics as MapServer output,
you don't have to compile it. However, by not compiling GD you also can't use
Truetype fonts--the GD that comes with Cygwin wasn't compiled with Freetype
support. If you want to use TrueType fonts but don't need GIF support, you can
use the "official" GD available from http://www.boutell.com/gd/.
To compile, cd to the GD directory ("cd ../gd-1.8.4") and type "./configure --help |more" to see the options available to the configure script. Use the "--enable-gnu-ld" option as well as make sure to include the freetype support. So, this time type "./configure --enable-gnu-ld --enable-freetype". Unfortunately, configure doesn't find the Freetype header files so you need to make a few changes in the Makefile. Edit the Makefile in your favorite text editor. Find the lines:
DEFS = -DPACKAGE=\"gd\" -DVERSION=\"1.8.4\" -DHAVE_LIBM=1 -DHAVE_LIBZ=1 -DHAVE_LIBPNG=1 -DSTDC_HEADERS=1 -DHAVE_MALLOC_H=1 -DHAVE_UNISTD_H=1 -DHAVE_ZLIB_H=1 -DHAVE_PNG_H=1 -I. -I$(srcdir)
CPPFLAGS = -I${prefix}/include -INONE
LDFLAGS = -L${exec_prefix}/lib -LNONE
and replace it with these:
DEFS = -DPACKAGE=\"gd\" -DVERSION=\"1.8.4\" -DHAVE_LIBTTF -DHAVE_LIBM=1 -DHAVE_LIBZ=1 -DHAVE_LIBPNG=1 -DSTDC_HEADERS=1 -DHAVE_MALLOC_H=1 -DHAVE_UNISTD_H=1 -DHAVE_ZLIB_H=1 -DHAVE_PNG_H=1 -I. -I$(srcdir)
CPPFLAGS = -I${prefix}/include/freetype -I${prefix}/include -I.
LDFLAGS = -L${exec_prefix}/lib -L.
Don't forget to save the changes. Now back to the console, type in "make" and wait for it to finish. Test whether the Freetype support worked by typing "./gdtestttf". It should give you the following message:
HEY! THIS IS FOR THE FREETYPE 1.x LIBRARY.
For better results, look at 'gdtestft' and the new gdImageStringFT function, which uses the new FreeType 2.x library.
libgd was not built with TrueType font support
This is a pretty daft message--ignore the last line. It does work. Don't install this library as it will conflict with the existing GD (Unless you really want to replace it... Don't ask me how.)
Other libraries.
If you want to compile other libraries, such as gdal/ogr or libwww. The process
will be similar in that you typically unpack the source code, run ./configure,
and make. Be sure to check the README files and run ./configure with --help
to see the available options. Oftentimes you will need to turn on or off a few
options. When you get to this point, experiment.
Well then... Off to MapServer.
At this point you might be tempted to just try running "./configure; make". But then again, you might have realized by now that it isn't all that straightforward. So, I'll go through this slowly. First, go to the mapserver directory and type "./configure --help" to review and think about what options to pass to the configure script. Now, if you've just gone ahead and typed "./configure" we wouldn't be able to make use of our new GD library since we didn't install it. So, you definitely need to use that "--with-gd=[DIR]" option. Also, the configure script may or may not find Proj.4 so you should also pass the "--with-proj=[DIR]" option. That's all you need for this example but if you add more libraries you might have to pass more options--GDAL, for example, need "--with-gdal=[gdal-config directory]". You also probably don't need the TIFF and JPEG libraries when using GDAL.
Anyway, back to our example. Type "./configure --with-gd=../gd-1.8.4 --with-proj=/usr/local" to generate our Makefile. After the Makefile is generated, check by opening it in your favorite text editor. Check to make sure that the "GD_LIB" line has -lttf and not -lfreetype (we're using Freetype 1.3, remember?). Also, check the "GD" line to make sure that there is a -DUSE_GD_TTF and not -DUSE_GD_FT. Lastly, check the "TIFF_LIB" line for -lttf and not -lfreetype.
Now you need to incorporate the regex workaround into the Makefile. I suppose we could have added it into the Makefile.in before running the configure script--you can do that if you want. Anyway, locate the lines:
REGEX_OBJ= @PHP_REGEX_OBJ@ REGEX_INC= @PHP_REGEX_INC@
and replace it with these:
REGEX_OBJ=regex-0.12/regex.o REGEX_INC=-I./regex-0.12 MAKE_REGEX=regex MAKE_REGEX_CLEAN=regex_clean
Now, add the following lines somewhere on the bottom of the Makefile, preferably after the "egis::" stuff:
regex:
cd regex-0.12; make; cd ..
Finally, add these lines after the "egis_clean:" stuff:
regex_clean:
cd regex-0.12; $(MAKE) clean; cd ..
Save any changes you make. You are now ready to compile. Go ahead, "make" your mapserv CGI.
When the compile process finishes, it should have created several executables (with .exe extension). Mapserv.exe is the CGI program that we need to build MapServer applications. The other executables are utilities for creating shapefile indices, sorting databases, and generating map and legend outputs. Test mapserv.exe by typing "./mapserv -v". It should produce the message:
$ ./mapserv -v MapServer version 3.5 (beta) OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP SUPPO RTS=PROJ SUPPORTS=TTF SUPPORTS=WMS_SERVER INPUT=TIFF INPUT=EPPL7 INPUT=JPEG INPU T=SHAPEFILE
and if you just type "./mapserv", you should get something like this:
This script can only be used to decode form results and should be initiated as a CGI process via a httpd server.
Congratulations! You've succesfully compiled MapServer on Cygwin. Now you're ready to install and use it.
As mentioned above, the Cygwin-compiled MapServer CGI program is only known to run on Apache. Apache itself is currently available on 2 flavors for Windows--as native compiled server or Cygwin-compiled. If you haven't yet installed one or the other, now is the time to choose. Binaries for Apache server can be downloaded from http://httpd.apache.org/dist/httpd/binaries/. If you would like the Cygwin-compiled binaries then go to the "cygwin" subdirectory, otherwise go to "win32". Extract the Cygwin-compiled package in your /usr/src/projects subdirectory. From there, you can read the installation instructions. The native Win32 binary package comes with its own installation instructions; please read before proceeding with MapServer installation.
If you use the Cygwin-compiled Apache server, installing MapServer will be straightforward--just put mapserv.exe in your cgi-bin directory and you're ready to go. You could now proceed with installing the MapServer demo package, or creating new applications.
However, if you prefer to use the "normal" Apache for Windows, you need to keep this in mind: install apache in a directory without a space character in its name. MapServer will not run if you install apache in it's default location--"c:\program files\apache group\apache". Instead, you should install in c:\apache or c:\apps\apache (or just c:\, where the installation will create an "apache" subdirectory). You also must include Cygwin's bin (C:\Cygwin\bin) directory in your system path. This can be done by right-clicking on "My Computer" and getting its "Properties". From the System Properties, select the "Advanced" tab and click on Environment variable. The rest you should be able to figure out. Remember that you need an administrator's privilege to change system settings. When you're done, just copy mapserv.exe to the cgi-bin directory.
As for the MapServer utility programs, I would put it in /usr/local/bin. You can install it in Cygwin by typing "make install" after compiling MapServer.
I'm in the process of collecting some well-known obstacles when compiling and using Cygwin-compiled MapServer. If you run into one, please let me know... all the better if you can provide any solutions as well. :)
LD_LIB_PATH (problems with libraries installed under /usr/local)
Apache-related problems
Norman Vine and David Fawcett answered some of my Apache-related questions. Stephen Woodbridge provided a few suggestions about this document. Jamie Smedsmo edited this otherwise poorly written HOWTO. Thanks to those guys. A few more people provided encouragement to write this document--thanks to them too! I hope it works for anyone who wishes to try the best of open-source/free software.