------------------------------------------------------------------ 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 ms_3.3.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[=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). --without-eppl Disable EPPL7 support. --with-eppl Include EPPL7 support. --without-ttf Disable Freetype (TTF) support. --with-ttf[=DIR] Include Freetype (TTF) support (DIR is Freetype's install dir). --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-ogr[=DIR] Include OGR support (DIR is OGR'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. --disable-debug Do not include -g in CFLAGS (the default). --with-php=DIR Specify directory where PHP3/PHP4 source tree is installed. Required in order to compile the PHP/MapScript module. --with-apxs[=FILE] 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 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 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. If it is not found then it uses "gd-1.2" that is included in the source code distribution. 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. 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. e.g. $ ./configure --with-tiff=../tiff-v.3.5.4 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. 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-ttf Disable Freetype (TTF) support. --with-ttf[=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 libttf on your system. Use --without-ttf to explicitly disable Freetype support. Use the --with-ttf=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. IMPORTANT NOTE IF YOU USE "--with-ttf=DIR": Since the Freetype distribution (freetype-1.3.1) is built as a shared library by default, then you have to make sure that libttf.so is located in a directory that is part of the system's runtime library path for your executables to work. If libttf cannot be installed in the system lib directories, then the best option is probably to add the directory where libttf.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. 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. 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 PHP3/PHP4 source tree is installed. Required in order to compile the PHP/MapScript module. --with-apxs[=FILE] 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 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. 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 PHP3 or PHP4 source distribution. The module was originally developped using php-3.0.14 and works with more recent versions of PHP3. It has also been ported to PHP4, and 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. You may have to start by recompiling Apache and PHP to include PHP as a module, there are step by step instructions for that on the PHP web site: http://www.php.net/manual/install-unix.php If PHP is compiled as a shared library Apache module, then you have to pass to the MapServer configure script the same value for the --with-apxs option that was passed to the PHP configure script. You can find the configure options that were used to build PHP on your system by looking at the "Configuration" section of the output of the PHP phpinfo() command. If PHP was compiled as an Apache module statically linked into the httpd executable then you have to use --with-apache=DIR to specify the location of the apache include files, likely /usr/local/apache/include. If you get errors at compile time about missing headers (ap_*.h, httpd.h, http*.h) then you need to use --with-apxs or --with-apache to help configure to find the location of the header files. 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. However, there is at least one exception that we know of: the Freetype library. You cannot have Freetype enabled in both PHP and MapServer because of a conflict with the gdttf.c and gdcache.c files that are included in both PHP and MapServer but are not identical. We may try to fix that conflict in the future, but in the meantime, one of PHP or MapServer has to be compiled using --without-ttf. This is especially important with PHP4 because it includes TTF support by default. Perl MapScript Module: ---------------------- The Perl MapScript module is not yet handled by the configure script. See the file ./mapscript/perl/README for compilation instructions. ---------------- $Id$ ----------------