|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| Author: | Pericles Nacionales |
|---|---|
| Contact: | pnaciona at gmail.com |
| Revision: | $Revision$ |
| Date: | $Date$ |
Table of Contents
This document provides a simple set of compilation procedures for MapServer on Win32 platforms.
If you’ve made it this far, chances are you already know about MapServer and are at least tempted to try compiling it for yourself. Pre-compiled binaries for MapServer are available from a variety of sources. Refer to Windows. Building MapServer for win32 platforms can be a daunting task, so if existing binaries are sufficient for your needs, it is strongly advised that they be used in preference to trying to build everything from source.
However, there can be a variety of reasons to want to build MapServer from source on win32. Reasons include the need to enable specific options, to build with alternate versions of support libraries (such as GDAL), the desire for MapScript support not part of the core builds, the need to debug and fix bugs or even to implement new features in MapServer. To make it easy for users and developers, I’ve made a list of steps to compile MapServer. Background information is provided in each step, along with examples. Each example is a continuation of the previous one and in the end will produce the MapServer DLL (libmap.dll), the CGI program (the mapserv.exe), and utility programs.
Warning
This document may refer to older library versions. You may want to try to use more recent library versions for your build.
If you are new to Windows programming, please follow this document carefully. The compilation steps are fairly simple but I’ve added a few blurbs in each step to help you understand how MapServer compiles. For the more experienced programmers, perhaps reading the README.Win32 that accompanies the MapServer source code would be more useful. For those who are antsy, compiling MapServer involves download and unpacking the source codes, editing the make files, and invoking Microsoft’s Visual C++ compiler from the command prompt. The resulting mapserv.exe is the CGI program that installs in the cgi-bin directory of your web server.
For those who are willing to take the time, the compilation steps follow.
Before you start to compile MapServer, I recommend creating a directory called “projects” where you can put the source code for MapServer and its supporting libraries. Since you will be working with DOS-style commands, you might as well get used to the Windows command prompt. For Windows 95/98 users the command processor would be called command.com. For Windows NT/2000/XP, it would be cmd.exe. So fire up the old command prompt and go to the drive where you want to create the project directory.
Here is an example of how to create a directory called projects on the C: drive:
C:\Users> mkdir C:\Projects
To go to that directory:
C:\Users> cd \Projects
C:\Projects>
From the projects directory, you can extract the source codes for MapServer and its libraries. Now you’re ready to download the source codes.
After creating a project directory, download the MapServer source code and the codes for the supporting libraries and save the source code packages in the newly created “projects” directory. These source codes are usually packaged as ZIP, or as UNIX TAR and GZIP files. You’ll need a software that can unzip these packages. 7-Zip is an example of software that can handle these files.
Cygwin is a free, open-source software package which is a port of these tools on Windows. You can use the gzip and tar utilities from this tool collection. Cygwin is available from http://www.cygwin.com.
In order to compile the MapServer CGI program, you must download a few required and optional libraries. At its simplest configuration, MapServer only requires the GD (to provide the image output) and REGEX (to provide regular expression support) libraries. This configuration allows the developer/data provider to use shapefiles as input and, depending on the version of GD library used, GIF or PNG images as output. Additional libraries are needed for input data in alternative formats. The libraries that work with MapServer are listed below.
The MapServer source code can be downloaded from the download page. If you’d like to get the current development version of the software, following the nightly snapshot link under the Interim Builds title. The absolute latest copy of the source code can be obtained from GitHub; however, the GitHub respository does not contain several important source files (maplexer.c, mapparser.c and mapparser.h) normally generated on unix, so if possible, using a nightly snaphot is substantially easier than working directly from GitHub.
Now that you have reviewed the libraries that provide support to MapServer, it is time to decide which ones to compile and use. We will work with the pre-built GD distributed on Boutell.com with PNG, GIF, JPEG, and FreeType “built in”. If you want to provide OGC Web Services (ie. WMS, WFS) or want to perform on the fly reprojection then the PROJ.4 library will be needed. If you need additional raster and vector data sources consider including GDAL/OGR support. GDAL is also required for WCS service.
Our example calls for the required libraries and on-the-fly projection support so we need to download GD, regex, and Proj.4 libraries. Go ahead and get those libraries.
MapServer, like many of it’s support libraries, comes with a Visual C++ makefile called Makefile.vc. It includes the file nmake.opt which contains many of the site specific definitions. We will only need to edit the nmake.opt file to configure the build for our local site options, and support libraries. The Makefile.vc, and nmake.opt template file have been provided by Assefa Yewondwossen, and the DM Solutions folks.
As of MapServer 4.4, the default MapServer build options only include GD, and regex. MapServer is built using the /MD option (which means MSVCRT.DLL should be used), so if any support libraries are being built statically (rather than as DLLs) we need to use /MD when building them as well. By default modern PROJ.4 builds use /MD so we should be able to use the default PROJ.4 build without tweaking.
The example will compile with the GDWin32 pre-built DLL as well as regex-0.12, and PROJ.4. The PROJ.4 support will ensure we can enable MapServer OGC-WMS compatibility. Use notepad or another text editor to open the nmake.opt file and make the following changes.
Use the pound sign ( # ) to comment out the lines that you want to disable, or remove the pound sign to enable an option for NMAKE.
A. Enable PROJ.4 support, and update the path to the PROJ.4 directory. Uncomment the PROJ= line, and the PROJ_DIR= line as follows, and update the PROJ_DIR path to point to your PROJ build.
# Reprojecting.
# If you would like mapserver to be able to reproject data from one
# geographic projection to another, uncomment the following flag
# Proj.4 distribution (cartographic projection routines). PROJ.4 is
# also required for all OGC services (WMS, WFS, and WCS).
#
# For PROJ_DIR use full path to Proj.4 distribution
PROJ=-DUSE_PROJ -DUSE_PROJ_API_H
PROJ_DIR=c:\projects\proj-4.4.9
If you look down later in the file, you can see that once PROJ is enabled, MapServer will be linked with proj_i.lib, the PROJ.4 stub library, meaning that MapServer will be using the PROJ.DLL as opposed to statically linking in PROJ.4.
# Use this flag to compile with WMS Server support.
# To find out more about the OpenGIS Web Map Server Specification go to
# http://www.opengis.org/
WMS=-DUSE_WMS_SVR
GD_DIR=c:/projects/gdwin32
GD_LIB=$(GD_DIR)/bgd.lib
Note: As distributed the GDWin32 binary build does not include the bgd.lib stub library. It is necessary to run the makemsvcimport.bat script in the gdwin32 directory first.
D. Make sure the regex path is set correctly. In order for the “delete” command in the “nmake /f makefile.vc clean” target to work properly it is necessary to use backslashes in the REGEX_DIR definition.
# REGEX Libary
#
# VC++ does not include the REGEX library... so we must provide our one.
# The following definitions will try to build GNU regex-0.12 located in the
# regex-0.12 sub-directory.
# If it was not included in the source distribution, then you can get it from:
# ftp://ftp.gnu.org/pub/gnu/regex/regex-0.12.tar.gz
# Provide the full path to the REGEX project directory
# You do not need this library if you are compiling for PHP mapscript.
# In that case the PHP regex library will be used instead
!IFNDEF PHP
REGEX_DIR=c:\projects\regex-0.12
!ENDIF
Your Makefile is now set.
Before compiling MapServer, you must first compile its supporting libraries. How this is done varies for each library. For the PROJ.4 library a nmake /f makefile.vc command in the proj-4.4.9src directory should be sufficient. The regex-0.12 code is actually built by the MapServer build process, so you don’t need to do anything there.
Previously, curl libraries can be compiled using the following command:
nmake /f makefile.vc6 CFG=release
This creates a static library, libcurl.lib, to which you compile against. Versions newer than version 7.10.x should be compiled as dynamic library. This is accomplished using the command:
nmake /f makefile.vc6 CFG=release-dll
You will then need to edit MapServer’s nmake.opt to replace the CURL_LIB variable with this line:
CURL_LIB = $(CURL_DIR)/lib/libcurl_imp.lib
Once you have compiled the supporting libraries successfully, you are ready to take the final compilation step. If you have not already done so, open a command prompt and set the VC++ environment variables by running the vcvars32.bat usually located in C:Program FilesMicrosoft Visual StudioVC98binvcvars32.bat.
C:\Users> cd \projects\mapserver
C:\Projects\mapserver&> C:\Program Files\Microsoft Visual Studio\VC98\Bin\vcvars32.bat"
C:\Projects\mapserver>
Setting environment for using Microsoft Visual C++ tool.
C:\Projects\mapserver>
Now issue the command: nmake /f Makefile.vc and wait for it to finish compiling. If it compiles successfully, you should get mapserver.lib, libmap.dll, mapserv.exe, and other .EXE files. That’s it for the compilation process. If you run into problems, read section 4 about compiling errors. You can also ask for help from the helpful folks in the MapServer-dev e-mail list.
To compile PostGIS support into MapServer, here’s what you need to do:
Following are a few common errors you may encounter while trying to build MapServer.
Visual C++ Tools Not Properly Initialized.
C:\projects\mapserver> nmake -f /makefile.vc 'nmake' is not recognized as an internal or external command, operable program or batch file.This occurs if you have not properly defined the path and other environment variables required to use MS VisualC++ from the command shell. Invoke the VCVARS32.BAT script, usually with the command C:Program FilesMicrosoft Visual StudioVC98binvcvars32.bat or something similar if visual studio was installed in an alternate location. To test if VC++ is available, just type “nmake” or “cl” in the command shell and ensure it is found.
Regex Build Problems.
regex.obj : error LNK2001: unresolved external symbol _printchar libmap.dll : fatal error LNK1120: 1 unresolved externals NMAKE : fatal error U1077: 'link' : return code '0x460' Stop.This occurs if you use the stock regex-0.12 we referenced. I work around this by commenting out the “extern” statement for the printchar() function, and replacing it with a stub implementation in regex-0.12regex.c.
//extern void printchar (); void printchar( int i ) {}GD Import Library Missing.
LINK : fatal error LNK1104: cannot open file 'c:/projects/gdwin32/bgd.lib' NMAKE : fatal error U1077: 'link' : return code '0x450' Stop.If you are using the pre-built GD binaries, you still need to run the makemsvcimport.bat script in the gdwin32 directory to create a VC++ compatible stub library (bgd.lib).
The file we are most interested in is mapserv.exe. The other executable files are the MapServer utility programs.
See also
to learn more about these utilities.
To test that the CGI program is working, type mapserv.exe at the command prompt. You should see the following message:
This script can only be used to decode form results and
should be initiated as a CGI process via a httpd server.
You may instead get a popup indicating that a DLL (such as bgd.dll) is missing. You will need to copy all the required DLLs (ie. bgd.dll, and proj.dll) to the same directory as the mapserv.exe program.
Now type mapserv -v at the command prompt to get this message:
MapServer version 4.4.0-beta3 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER INPUT=SHAPEFILE
DEBUG=MSDEBUG
This tells us what data formats and other options are supported by mapserv.exe. Assuming you have your web server set up, copy mapserv.exe, libmap.dll, bgd.dll, proj.dll and any other required DLLs to the cgi-bin directory.
You are now ready to download the demo application and try out your own MapServer CGI program. If you wish, you can also create a directory to store the utility programs. I’d suggest making a subdirectory called “bin” under the directory “projects” and copy the executables to that subdirectory. You might find these programs useful as you develop MapServer applications.
The MapServer Unix Compilation and Installation HOWTO has good descriptions of some MapServer compilation options and library issues. I will write more about those options and issues on the next revision of this HOWTO.
The README documents of each of the supporting libraries provide compilation instructions for Windows.
The MapServer User community has a collective knowledge of the nuances of MapServer compilation. Seek their advice wisely.
Thanks to Assefa Yewondwossen for providing the Makefile.vc. I would not have been able to write this HOWTO without that file.
Thanks to Bart van den Eijnden for the libcurl and PostGIS compilation info.
Thanks to the Steve Lime for developing MapServer and to the many developers who contribute time and effort in order to keep the MapServer project successful.