README.CONFIGURE

------------------------------------------------------------------
README.CONFIGURE - MapServer "configure" script compilation options
-------------------------------------------------------------------

For Unix users, Mapserver comes with a GNU autoconf "configure" script 
that should take care of (hopefully!) all compilation issues for you.

The configure script won't work on Windows NT.  See the file README.WIN32
for details on compiling on Windows systems.

The default configure behavior is to try to locate on your system the most
common optional libraries that MapServer can use and include them in the
Makefiles.  It also takes care of setting the proper compilation flags to
handle issues like the version of GD that you are using, etc.


For the impatient:
------------------

To build the "mapserv" CGI program with the default options, go to the
directory where you extracted the MapServer source code package and...

 $ cd mapserver-4.0.x
 $ ./configure
 $ make

Unless something went wrong, you should have executables in the current 
directory for the "mapserv" CGI program and the other utility programs.
You can copy the "mapserv" program to your HTTP server's CGI directory
and start using it.  

See the MapServer web site at http://mapserver.gis.umn.edu/ for usage
instructions.


"configure" options:
--------------------

Here is the list of available options as returned by "./configure --help":


  --with-jpeg[=DIR]       Include JPEG support (DIR is LibJPEG's install dir).
  --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-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).
  --without-pdf           Disable PDF support.
  --with-pdf[=DIR]        Include PDF support (DIR is PDFlib's install dir).
  --without-tiff          Disable TIFF support.
  --with-tiff[=DIR]       Include TIFF support (DIR is LibTIFF's install dir).
  --without-eppl          Disable EPPL7 support.
  --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)
  --without-wms           Disable OGC WMS Compatibility (enabled by default).
  --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.
  --enable-ignore-missing-data   Ignore missing data file errors at runtime
                                 (enabled by default).
  --disable-ignore-missing-data  Report all missing data files.
  --enable-debug          Include -g in CFLAGS for debugging and enable
                          msDebug() output to stderr (i.e. server log file).
  --disable-debug         Do not include -g in CFLAGS and disable msDebug()
                          output (the default).
  --with-php=DIR          Specify directory where PHP4 source tree is
                          installed. Required in order to compile the
                          PHP/MapScript module.
  --enable-perlv-ld-detect (applies to --with-php only) 
                          Use perl -V output to figure the command to use to 
                          link php_mapscript.so.  Try this only if the default
                          internal macro didn't work.
  --with-apxs[=FILE]      (CURRENTLY DISABLED) 
                          Use this option only if building the PHP MapScript
                          on a system where PHP was built as a shared Apache
                          module.  FILE is the optional pathname to the
                          Apache apxs tool; defaults to apxs.
  --with-apache=DIR       (CURRENTLY DISABLED) 
                          Use this option only if building the PHP MapScript
                          on a system where PHP was built as an Apache
                          module statically linked into the httpd executable.
                          DIR is the path to the apache include files.
  --enable-runpath        Include runtime library path flags (-Wl,-R) in link.
                          Required on *BSD systems.
  --disable-runpath       Do not link with runtime lib path (the default).


All the options are described in more details below.


GD and Support Libraries:
-------------------------

  --with-gd[=DIR]         Specify which version of GD to use (DIR is GD's
                          install dir).


  The GD library is the only component that is not optional.  
  Version 2.0.12 or more recent is required, see http://www.boutell.com/gd/ .

  By default, configure tries to locate it on your system and uses the
  system copy if found.   

  You can use the --with-gd=DIR option to use a copy of GD installed in
  directory "DIR".  Make sure that this copy of GD is compiled before
  using this option.

  GD has dependencies on a few external libraries and it may be necessary 
  to explicitly specify the path where those libraries are found using the
  following configure options:

  --with-jpeg[=DIR]       Include JPEG support (DIR is LibJPEG's install dir).
  --with-libiconv=DIR     GD: Specify where libiconv is installed (DIR is path to
                              libiconv 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).

  In each case you specify the install dir of the support library, e.g.
    ./configure .... --with-gd=/usr/local --with=jpeg=/usr/local \
                     --with-png=/usr/local --with-zlib=/usr/local


  Note:  If libraries required by GD are not found, it may cause configure
  to not accurately detect which image formats are supported by GD, and may
  cause configure and building to fail.



TIFF Support:
-------------

  --without-tiff          Disable TIFF support.
  --with-tiff[=DIR]       Include TIFF support (DIR is LibTIFF's install dir).

  Tiff support is optional, but it will be included by default if configure
  finds libtiff on your system.

  Use --without-tiff to explicitly disable Tiff support.

  Use the --with-tiff=DIR option to use a copy of LibTiff installed in
  directory "DIR".  Make sure that this copy of LibTiff is compiled before
  using this option.

  Note:  Your version of libtiff may have been compiled with JPEG or ZLIB
  support.  If so, you may need to specify --with-jpeg=DIR or --with-zlib=DIR
  to resolve these libraries for linking.  Failure to resolve dependent
  libraries may cause linking to fail.



EPPL7 Support:
--------------

  --without-eppl          Disable EPPL7 support.
  --with-eppl             Include EPPL7 support.

  EPPL7 support is optional and does not require linking with any external 
  library.

  It will be included by default, and can be disabled with --without-eppl.



PROJ.4 Support:
---------------

  --with-proj[=DIR]       Include PROJ.4 support (DIR is PROJ.4's install dir).

  PROJ.4 support is optional, and is not included by default.

  You have to use the --with-proj=DIR option to enable PROJ.4 support and
  specify where PROJ.4 installed.  Make sure that this copy of PROJ.4 is 
  compiled before using this option.

  Starting with MapServer v3.5, PROJ.4.4.2 (or more recent) is required.

  You may also have to install the NADCON data files in order to enable
  datum shift support if you installed a source distribution.  Look for 
  proj-nadus-1.0.tar.gz at  http://www.remotesensing.org/proj/.


ESRI SDE Support:
-----------------

  --with-sde[=DIR]        Include ESRI SDE support (DIR is SDE's install dir).

  ESRI SDE support is optional, and is not included by default.  

  You have to use the --with-sde=DIR option to enable ESRI SDE support and
  specify where ESRI SDE is installed.


OGR Support:
------------

  --with-ogr[=PATH]       Include OGR support (PATH is path to gdal-config).

  OGR support is optional, and is not included by default.  

  The OGR library (http://gdal.velocet.ca/projects/opengis/) allows MapServer
  to access data in a variety of vector formats, see the URL above for the
  complete list.

  You have to use the --with-ogr[=PATH] option to enable OGR support and
  specify where the 'gdal-config' script for your installation is located.

    e.g.    ./configure ...  --with-ogr=/usr/local/bin/gdal-config

  OGR is usually installed as part of a GDAL shared library.  To get the
  full GDAL and OGR source kit visit http://www.remotesensing.org/gdal .
  When configuring GDAL ensure that --with-ogr is selected.
  Then when you configure MapServer, include the --with-ogr switch with
  no argument since the location of the GDAL lib also defines the OGR 
  location in this case.  See the GDAL section below for more details 
  on using --with-gdal and --with-ogr together.



GDAL Support:
-------------

  --with-gdal[=path]     Include GDAL support (path is to gdal-config script).

  GDAL support is optional, and it is not included by default. 

  The GDAL library (http://www.remotesensing.org/gdal) allows MapServer
  to access data in a variety of raster formats, including GeoTIFF, Erdas
  Imagine, ESRI BIL, and CEOS. 

  If GDAL is installed (ie. in /usr/local) then it should be sufficient
  to say --with-gdal, but if the gdal-config script cannot be found, please
  use --with-gdal=/usr/local/bin/gdal-config, or whatever path is is required
  to get the gdal-config script. 

  Note that it is possible to compile GDAL/OGR independently or not in 
  MapServer:

  1- GDAL only using libgdal.so installed in system lib dirs, this assumes
     you have previously run 'make install' as root in your GDAL source
     tree:
      ./configure --with-gdal
     or 
      ./configure --with-gdal=/usr/local/bin/gdal-config
     (or whatever the path to the installed gdal-config script is.)

  2- OGR only, using libgdal.so installed in system lib dirs, once again
     this assumes you have previously run 'make install' as root in your 
     GDAL source tree:
      ./configure --with-ogr
     or 
      ./configure --with-ogr=/usr/local/bin/gdal-config
     (or whatever the path to the installed gdal-config script is.)

  3- GDAL and OGR using libgdal.so, assuming that GDAL was configured with 
     --with-ogr.  Same as #1 above, but add --with-ogr with no argument to
     the MapServer configure command:
      ./configure --with-gdal --with-ogr
     or 
      ./configure --with-gdal=/usr/local/bin/gdal-config --with-ogr


PostGIS Support:
---------------

  --with-postgis[=ARG]   Include PostGIS Support (ARG=yes/path to pg_config)

  PostGIS support is optional, and it is not included by default. 

  PostGIS support (http://postgis.refractions.net) allows Mapserver
  to access geographic data stored in a PostgreSQL (http://www.postgresql.org)
  database using the PostGIS server extensions. PostGIS is only supported
  on PostgreSQL version 7.1.2 or better. PostGIS supports vector (point,
  line, polygon) data only.

  To access a PostGIS/PostgreSQL data-source, the machine on which 
  Mapserver is running must have the PostgreSQL client libraries
  (libpq) installed. To compile Mapserver with PostGIS/PostgreSQL support
  the PostgreSQL header files must also be present. The 'pg_config' program
  is included with the PostgreSQL distribution. If it is not already
  in your path ('which pg_config'), then specify exactly where it can
  be found.



MyGIS (MySQL v3.xx SFSQL) Support:
----------------------------------

  --with-mygis[=ARG]      Include MyGIS Support (ARG=yes/path to my_config)

  MyGIS provides OGC SFSQL support using MySQl v3.xx.  This option is 
  disabled by default and can be enabled using the --with-mygis option.

  For more details see the MapServer Wiki at:
  http://mapserver.gis.umn.edu/cgi-bin/wiki.pl?MySQL


Oracle Spatial Support:
-----------------------

  --with-oraclespatial[=ARG] Include OracleSpatial Support (ARG=yes/path to Oracle home)

  Oracle Spatial support is optional and is not included by default. 

  For more details see the MapServer Wiki at:
  http://mapserver.gis.umn.edu/cgi-bin/wiki.pl?OracleSpatial



Flash/SWF/Ming Output Support:
------------------------------

  --with-ming[=ARG] Include MING/Flash Support (ARG=yes/path to Ming directory)

  Support for generating Flash output is enabled only if requested.  Use
  the --with-ming switch to request it if the ming libraries have been 
  installed in the default path.  To use a local ming build also provide the
  path to the ming build directory.

  The IMAGETYPE for Flash output is SWF.  

  More information on the MING library should be available at:
  http://www.opaque.net/ming/



PDF output support:
-------------------

  --without-pdf           Disable PDF support.
  --with-pdf[=DIR]        Include PDF support (DIR is PDFlib's install dir).

  Support for PDF output using PDFLib (http://www.pdflib.com/pdflib/)
  is disabled by default and can be enabled using the --with-pdf option.

  If PDFLib is installed in the default system directories then using 
  --with-pdf with no argument should be enough.  If not then pass the 
  full path to the PDFLib installation directory.
  e.g.
      ./configure ..... --with-pdf=/usr/local

  For more informations, see the MapServrer Wiki at
  http://mapserver.gis.umn.edu/cgi-bin/wiki.pl?MapserverPDF

  IMPORTANT NOTE: PDFLib comes bundled with and is built by default using
  its own internal copy of libpng and zlib.  The PDFLib internal copy of
  those libpng and zlib are very likely of different versions from the
  ones used by the GD library.  Loading both versions could lead to 
  crashes or instability of your MapServer or MapScript installation.  
  For this reason you should make sure that your PDFLib is configured 
  using '--with-pnglib --with-zlib' which will force PDFLib to use the 
  system verison of libpng and zlib.


OGC WMS Server Compatibility:
-----------------------------

  --without-wms           Disable OGC WMS Compatibility (enabled by default).

  OGC WMS Compatibility is enabled by default if PROJ.4 is included.

  WMS Compatibility allows MapServer (actually the mapserv CGI) to advertize
  its capabilities and serve maps and feature_info requests following the 
  OpenGIS Web Mapping Server (WMS) Interface Specification.

  See the MapServer WMS Server HOWTO at 
  http://mapserver.gis.umn.edu/doc/wms-server-howto.html


OGC WMS Client Support:
-----------------------

  --with-wmsclient        Enable OGC WMS Client Connections (PROJ4 and libcurl
                          required).

  This option enables MapServer's 'CONNECTIONTYPE WMS' to include layers
  from remote WMS servers in MapServer applications.
  It requires PROJ4, libcurl (see  --with-curl-config option below) and OGR.
  GDAL is optional but highly recommended in order to support 
  reprojection of layers obtained from remote WMS servers.

  See the MapServer WMS Client HOWTO for more details at 
  http://mapserver.gis.umn.edu/doc/wms-client-howto.html


OGC WFS Server Compatibility:
-----------------------------

  --with-wfs              Enable OGC WFS Server Support (OGR+PROJ4 required).

  This option is used to enable the OGC WFS server extension.  It requires
  the OGR and PROJ4 options as well.

  See the MapServer WFS Server HOWTO at 
  http://mapserver.gis.umn.edu/doc/wms-server-howto.html


OGC WMS Client Support:
-----------------------

  --with-wfsclient        Enable OGC WFS Client Connections (PROJ4, libcurl and
                          OGR required).

  This option enables MapServer's 'CONNECTIONTYPE WFS' to include layers
  from remote WFS servers in MapServer applications.
  WFS client support in MapServer requires PROJ4, libcurl and an installation 
  of OGR compiled with the Xerces library (for GML support via OGR).

  See the MapServer WMS Client HOWTO for more details at 
  http://mapserver.gis.umn.edu/doc/wfs-client-howto.html



Curl Support:
-------------

  --with-curl-config=PATH Specify path to curl-config.

  The Curl library (http://curl.haxx.se/libcurl/) is used by the WMS 
  Client and WFS client options to connect to remote servers via HTTP.

  LibCurl 7.10.1 or more recent is required with the current version 
  of MapServer.

  If libcurl is installed in the default system directories then it 
  should automatically be detected by configure.  Otherwise use the
  --with-curl-config option to specify the path where the curl-config
  script is located.
  e.g.
     ./configure .... --with-curl-config=/usr/local/bin/curl-config



Miscellaneous flags:
--------------------

  --with-threads[=linkopt]Include thread safe support

  --with-mpatrol[=DIR]    Include MPATROL support (DIR is MPATROL's install dir).

  --enable-ignore-missing-data   Ignore missing data file errors at runtime
                                 (enabled by default).
  --disable-ignore-missing-data  Report all missing data files.

  --enable-debug          Include -g in CFLAGS for debugging and enable
                          msDebug() output to stderr (i.e. server log file).
  --disable-debug         Do not include -g in CFLAGS and disable msDebug()
                          output (the default).

  --enable-runpath        Include runtime library path flags (-Wl,-R) in link.
                          Required on *BSD systems.
  --disable-runpath       Do not link with runtime lib path (the default).


  NOTE FOR *BSD USERS ABOUT --enable-runpath:

    For some reason, the --enable-runpath switch is required in order to 
    successfully link on *BSD systems.  For most other operating systems
    you don't need the --enable-runpath switch unless you link MapServer
    with some shared libraries located outside of the system's runtime 
    library path.  And even then, it is probably preferable to use 
    "setenv LD_LIBRARY_PATH ..." in Apache's httpd.conf to set the mapserv
    CGI or MapScript runtime library path.


PHP/MapScript module:
----------------------

  --with-php=DIR          Specify directory where PHP4 source tree is
                          installed. Required in order to compile the
                          PHP/MapScript module.
  --enable-perlv-ld-detect (applies to --with-php only) 
                          Use perl -V output to figure the command to use to 
                          link php_mapscript.so.  Try this only if the default
                          internal macro didn't work.


  The --with-php option will trigger the compilation of the PHP MapScript
  module in the ./mapscript/php3/ directory.  

  DIR should be the location of the PHP4 source distribution.  The 
  module currently requires PHP 4.1.2 or more recent. The configure 
  script should automatically detect which version of PHP you 
  are attempting to build with and take the necessary actions.

    e.g.  $ ./configure --with-php=../php-4.3.2

  The PHP module has to be built as a shared library that will then
  be loaded as a Dynamic Module by the PHP interpreter using the dl()
  PHP command.  See the Wiki for detailed build instructions for various
  platforms: http://mapserver.gis.umn.edu/cgi-bin/wiki.pl?PHPMapScript
  See also the file ./mapscript/php3/README for more details on the
  MapScript classes and functions.  

  Note that PHP MapScript currently works only with PHP installed as a CGI
  and will not work with PHP as an Apache module.  For more details, see
    http://mapserver.gis.umn.edu/cgi-bin/wiki.pl?PHPMapScriptCGI

  Some libraries are used by both PHP and MapServer, and using different 
  versions of these libs will lead to potential crashes at runtime.  In most
  cases it is safe to have both PHP and MapServer compiled with the same 
  libraries (e.g. GD, regex, etc.) as long as they are of the same versions.


Perl MapScript Module:
----------------------

  The Perl MapScript module is not yet handled by the configure script.

  See the file ./mapscript/perl/README for compilation instructions.


Python MapScript Module:
------------------------

  The Python MapScript module is not yet handled by the configure script.

  See the file ./mapscript/python/README for brief compilation instructions.


Tcl MapScript Module:
---------------------

  The Tcl MapScript module is not yet handled by the configure script.

  See the file ./mapscript/tcl/README for compilation instructions.

  Mapserver must first be configured and build before building Tcl
  MapScript.



----------------
$Id$
----------------