------------------------------------------------------------------ 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-3.6.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-gd[=[static,]DIR] Specify which version of GD to use (DIR is GD's install dir). --without-tiff Disable TIFF support. --with-tiff[=DIR] Include TIFF support (DIR is LibTIFF's install dir). --without-jpeg Disable JPEG support. --with-jpeg[=DIR] Include JPEG support (DIR is LibJPEG's install dir). --with-zlib[=DIR] Specify where to find ZLIB, if needed by GD. --with-png[=DIR] Specify where to find PNG, if needed by GD. --with-freetype[=DIR] Specify where to find Freetype, if needed by GD. --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-sde[=DIR] Include ESRI SDE support (DIR is SDE's install dir). --with-mpatrol[=DIR] Include MPATROL support (DIR is MPATROL's install dir). --with-ogr[=DIR] Include OGR support (DIR is OGR's install dir). --with-gdal[=DIR] Include GDAL support (DIR is path to gdal-config --with-postgis[=ARG] Include PostGIS Support (ARG=yes/path to pg_config) --with-oraclespatial[=ARG] Include OracleSpatial Support (ARG=yes/path to Oracle home) --with-ming[=ARG] Include MING/Flash Support (ARG=yes/path to Ming directory) --without-wms Disable OGC WMS Compatibility (enabled by default). --with-wmsclient Enable OGC WMS Client Connections (PROJ4 and libwww required). --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. --disable-debug Do not include -g in CFLAGS (the default). --with-php=DIR Specify directory where PHP4 source tree is installed. Required in order to compile the PHP/MapScript module. --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 Library: ----------- --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. 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. Newer versions of GD generate JPEG, PNG, and WBMP image formats instead of GIF, and may use FreeType for fonts. This may require GD linking with those libraries. Use specific --with-jpeg=DIR, --with-freetype=DIR, --with-png=DIR, --with-zlib=DIR options as noted below to find those libraries if required, configure checks in standard locations for defaults. 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. JPEG Support: ------------- --without-jpeg Disable JPEG support. --with-jpeg[=DIR] Include JPEG support (DIR is LibJPEG's install dir). JPEG support is optional, but it will be included by default if configure finds libJPEG on your system. Use --without-jpeg to explicitly disable JPEG support. Use the --with-jpeg=DIR option to use a copy of LibJPEG installed in directory "DIR". Make sure that this copy of LibJPEG is compiled before using this option. Also use this option if your version of GD produces images in JPEG format. PNG Support: ------------ --with-png[=DIR] Specify where to find PNG libraries. Your GD library may produce images in PNG format. Use this option to specify a specific PNG installation directory. The default location is the system library. ZLIB Support: ------------- --with-zlib[=DIR] Specify where to find ZLIB (libz) libraries. Your GD library may produce images in PNG format. Use this option to specify a specific ZLIB installation directory, as PNG and/or TIFF may depend on this library. 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. Freetype Support: ----------------- --without-freetype Disable Freetype (TTF) support. --with-freetype[=DIR] Include Freetype (TTF) support (DIR is Freetype's install dir). Freetype support is optional, but it will be included by default if configure finds libfreetype (or libttf) on your system. Use the --with-freetype=DIR option to use a copy of Freetype installed in directory "DIR". Make sure that this copy of Freetype is compiled before using this option. Beginning with FreeType 2.x+, FreeType installs 'freetype-config' into the installation directory as ./bin/freetype-config. You may specify the pathname to freetype-config as the DIR argument. E.g.: --with-freetype=/usr/local/bin/freetype-config IMPORTANT NOTE IF YOU USE "--with-freetype=DIR": Since the Freetype distribution is built as a shared library by default, then you have to make sure that libfreetype.so is located in a directory that is part of the system's runtime library path for your executables to work. If libfreetype cannot be installed in the system lib directories, then the best option is probably to add the directory where libfrretype.so lives to the LD_LIBRARY_PATH environment variable and make sure that its value gets passed to CGI programs. With Apache, this is done with the PassEnv or the SetEnv directives in the httpd.conf file. e.g. Add to httpd.conf: setenv LD_LIBRARY_PATH /path/to/my/libs and restart httpd. Common problem: LibTTF came pre-installed on my system, but freetype.h is not found. On some systems such as RedHat Linux, the freetype library comes installed by default, but the headers are not. You will have to install the freetype-devel RPM that came with the Linux CD and then re-run configure. 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[=DIR] Include OGR support (DIR is OGR's install dir). 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 multiple vector formats. You have to use the --with-ogr=DIR option to enable OGR support and specify where the OGR (or GDAL) source tree is located. Make sure that this copy of OGR is compiled before using this option. This will link OGR statically into the MapServer executable. OGR can also be 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. If mapogr.cpp won't compile due to the lack of ogr_featurestyle.h, please copy from gdal-version/ogr/ogr_featurestyle.h into the install include directory (ie. /usr/local/include) or upgrade to GDAL 1.1.4 or later. 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 there are several ways to compile GDAL/OGR independently or not in MapServer: 1- OGR only, statically linked into MapServer, then you point configure directly to the ogr source tree after having compiled OGR: ./configure --with-ogr=/path/to/ogr/source 2- 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.) 3- GDAL and OGR using libgdal.so, assuming that GDAL was configured with --with-ogr. Same as #2 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. Flash/SWF/Ming 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/ 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 libwww required). This option enables MapServer's 'CONNECTIONTYPE WMS' to include layers from remote WMS servers in MapServer applications. It requires PROJ4 and W3C's libwww. 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 Note: A conflict has been reported on systems on which the rxposix library was installed (MapServer wants to use the system regex and libwww wants to use rxposix). See MapServer bug#82 for the details at http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=82 Miscellaneous flags: -------------------- --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. --disable-debug Do not include -g in CFLAGS (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. 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-3.0.14 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 file ./mapscript/php3/README for more details. 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$ ----------------