.. index::
   pair: Win32; Installation

.. index::
   pair: Win32; Compilation

.. _win32:

*****************************************************************************
 Compiling on Win32 
*****************************************************************************

:Author:  Pericles Nacionales   
:Contact: pnaciona at gmail.com

.. contents:: Table of Contents
    :depth: 2
    :backlinks: top

.. 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/master/README.WIN32.
    See also https://github.com/mapserver/mapserver/blob/master/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 :ref:`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.

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. 

.. _`7-Zip`: http://www.7-zip.org/

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 
:ref:`download page <download>`. 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 :ref:`git`; 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 :ref:`git`.

**Required Libraries**
----------------------

.. _`GD Library`: http://www.libgd.org/

`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`: http://www.ijg.org/

`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`: http://www.libpng.org/pub/png/

`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`:  http://www.gzip.org/zlib/

`Zlib`_:
   This library is required by libpng to provide graphics 
   compression support.  It can be downloaded along with the PNG library, or at 
   http://www.gzip.org/zlib.zip .

.. _`FreeType 2`: http://www.freetype.org/

`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.4`: http://trac.osgeo.org/proj/

`PROJ.4`_:
  PROJ.4 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`: http://www.gdal.org/

`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
    http://www.gdal.org/.

.. _`ArcSDE`: http://www.esri.com/software/arcgis/arcsde/

`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`: http://www.lmic.state.mn.us/resource.html?Id=3603

`EPPL7`_:
    This library allows MapServer to read EPPL7 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.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.

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

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

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

C. 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.4 library
a **nmake /f makefile.vc** command in the proj-4.4.9\src 
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 Files\Microsoft Visual Studio\VC98\bin\vcvars32.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:\projects\postgresql-8.0.1
3. download the `Microsoft Platform SDK 
   <http://www.microsoft.com/downloads/details.aspx?familyid=E6E1C3DF-A74F-4207-8586-711EBE331CDC&displaylang=en>`__ 
   otherwise you get link errors on shfolder.lib.
4. compile libpq under C:\projects\postgresql-8.0.1\src\interfaces\libpq 
   using the win32.mak makefile
5. copy everything from C:\projects\postgresql-8.0.1\src\interfaces\libpq\release 
   to C:\projects\postgresql-8.0.1\src\interfaces\libpq 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:\projects\postgresql-8.0.1\src\interfaces\libpq\release) 
   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 Files\Microsoft
   Visual Studio\VC98\bin\vcvars32.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.12\regex.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. 

.. seealso::
    :ref:`MapServer Utilities <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.

