Compiling on Win32

Author

Pericles Nacionales

Contact

pnaciona at gmail.com

Warning

This part of the documentation is outdated. nmake is no longer used. cmake is used also for Win32. cmake instructions can be found on https://github.com/MapServer/MapServer/blob/main/README.WIN32. See also https://github.com/MapServer/MapServer/blob/main/appveyor.yml.

Introduction

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.

Compiler Requirements

As of MapServer 8.0, a C++11 and C99 capable compiler is required to build MapServer. This means for example using Microsoft Visual Studio 2015 or more recent.

Compiling

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.

Set up a Project Directory

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.

Download MapServer Source Code and Supporting Libraries

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

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 repository 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.

Required Libraries

GD Library:

MapServer uses the GD graphics library for rendering map images in GIF, PNG and JPEG format. These map images are displayed in web browser clients using the MapServer CGI. The current official version of GD is 2.0.33. The distributed makefiles are setup to use the prebuilt GD Win32 DLL binaries which include GD, libjpeg, libpng, libz, libgif and FreeType 2 all within one DLL. This package is generally listed as “Windows DLL .zip” and the latest version is normally available at http://www.boutell.com/gd/http/gdwin32.zip.

Regex:

Regex is the regular expression library used by MapServer. It can be downloaded at http://ftp.gnu.org/old-gnu/regex/regex-0.12.tar.gz

Optional Libraries

JPEG library:

This library is required by GD to render JPEG images, if building GD from source. You may download this library at http://www.ijg.org/files/jpegsrc.v6b.tar.gz

PNG library:

This library is required by GD to render PNG images, if building GD from source. You may download this library at http://sourceforge.net/projects/libpng/

Zlib:

This library is required by libpng to provide graphics compression support. It can be downloaded at https://zlib.net/ .

FreeType 2:

FreeType provides TrueType support in MapServer via GD. We only need to build FreeType separately if building GD from source. It can be downloaded at http://gnuwin32.sourceforge.net/packages/freetype.htm .

PROJ:

PROJ provides on-the-fly projection support to MapServer. Users whose data are in different projection systems can use this library to reproject into a common projection. It is also required for WMS, WFS or WCS services.

GDAL/OGR:

The GDAL/OGR library allows MapServer to read a variety of geospatial raster formats (GDAL) and vector formats (OGR). It can be downloaded at https://gdal.org/.

ArcSDE:

ArcSDE is an ESRI proprietary spatial database engine. Most users will not have access to it but if you have ArcSDE license, you can use its libraries to give MapServer access to SDE databases.

EPPL7:
This library allows MapServer to read EPPL7 (“Environmental Planning and Programming

Language”) datasets, as well as the older Erdas LAN/GIS files. This library is set as a default library in MapServer so there’s no special source code to download.

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 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 libraries. Go ahead and get those libraries.

Set Compilation Options

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 builds use /MD so we should be able to use the default PROJ build without tweaking.

The example will compile with the GDWin32 pre-built DLL as well as regex-0.12, and PROJ. The PROJ 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.

Comments

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 support, and update the path to the PROJ 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 distribution (cartographic projection routines).  PROJ is
# also required for all OGC services (WMS, WFS, and WCS).
#
# For PROJ_DIR use full path to PROJ 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 stub library, meaning that MapServer will be using the PROJ.DLL as opposed to statically linking in PROJ.

  1. Uncomment the WMS option.

# 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

  1. Update to use GD. Here’s what it should look like in our example.

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 Library
#
# 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.

Compile the Libraries

Before compiling MapServer, you must first compile its supporting libraries. How this is done varies for each library. For the PROJ 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.

Compiling libcurl

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

Compile MapServer

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.

Compiling MapServer with PostGIS support

To compile PostGIS support into MapServer, here’s what you need to do:

  1. download the PostgreSQL 8.0.1 (or later) source from: ftp://ftp.heanet.ie/pub/postgresql/source/

  2. I extracted them to C:projectspostgresql-8.0.1

  3. download the Microsoft Platform SDK otherwise you get link errors on shfolder.lib.

  4. compile libpq under C:projectspostgresql-8.0.1srcinterfaceslibpq using the win32.mak makefile

  5. copy everything from C:projectspostgresql-8.0.1srcinterfaceslibpqrelease to C:projectspostgresql-8.0.1srcinterfaceslibpq as the MapServer makefile will try to find it there

  6. Define the following in the nmake.opt for MapServer: POSTGIS =-DUSE_POSTGIS POSTGIS_DIR =c:/projects/postgresql-8.0.1/src

  7. nmake /f makefile.vc

  8. don’t forget to copy libpq.dll (from C:projectspostgresql-8.0.1srcinterfaceslibpqrelease) into a location where MapServer can find it.

Common Compiling Errors

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).

Installation

The file we are most interested in is mapserv.exe. The other executable files are the MapServer utility programs.

See also

MapServer Utilities

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.

Other Helpful Information

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.

Acknowledgements

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.