<title>Building GDAL From Source</title>
Building on Unix
GDAL has been successfully built on Linux, IRIX, Solaris, BSD, and MacOS X. On Unix platforms you might be able to build it as follows (assuming it is unpacked or checked out of CVS as gdal):
% cd gdal
% ./configure
% make
% su
Password: ********
# make install
# exit
In order to run GDAL after installing it is necessary for the shared library to be findable. This can often be accomplished by setting LD_LIBRARY_PATH to include /usr/local/lib.
Some caveats are:
-
I depend on GNUmake on Unix platforms. Just get and install it if you don't already have it.
-
GDAL shouldn't have many pre-requisite packages. It includes built-in versions of libz, libtiff, libgeotiff, libpng, libgif, and libjpeg if pre-installed versions are not available (or not desirable).
-
There are quite a few optional drivers that depend on external libraries. Use "configure --help" to see the configure options. Some optional libraries include those for GRASS, FITS, OGDI, HDF4, JPEG2000 and ECW.
-
The shared library building is pretty specific to the GNU tool chain. If you are using something different than GNU C++, then you will likely finding that the .so files isn't built successfully. You could just link against the static libraries (normally gdal/gdal.a gdal/ogr/ogr.a gdal/frmts/o/ *.a gdal/gdal.a gdal/port/cpl.a) or you could hack LD_SHARED command in gdal/GDALmake.opt to work on your platform. For the SGI a value of "c++ -shared -all" is often suitable.
-
GDAL, and it's utilities should now build on Cygwin and other platforms where shared libraries are not supported. However, to build your own applications against it, you will need to link against a more extensive set of libraries. The gdal-config --libs command can be used to determine the library set.
-
My "autoconf" logic that checks for libtiff, libpng and libjpeg isn't too savvy about versions. If it is using pre-installed versions of these libraries and this support isn't working, rerun configure with ``--with-png=internal'', ``--with-jpeg=internal'', ``--with-geotiff=internal'' or ``--with-libtiff=internal'' instead.
-
To build on IRIX it is generally necessary to hand modify the GDALmake.opt file resulting from configure, and change "ld -shared" to "ld -shared -all".
-
If you find build problems with one of the format drivers that you don't care about, just remove the format from the GDAL_FORMATS line at the bottom of gdal/GDALmake.opt, do a make clean, and make. This will drop it from the build and default runtime registration.
-
If you are trying to install as other than root (to your own tree set with --prefix) you will likelyhave problems with the python since it always tries to install under the site-packages directory for the installed python tree. If you don't need python support you can supress it at configure using --without-python, or override the python module output directory at configure time with the --with-pymodir=<directory>
Building on Windows
GDAL can be built on Windows using MS VC++ 6.x and MS Visual Studio .NET (C++) at the DOS command line. For this to work you will normally have to have run the VCVAR32.BAT script that comes with the compiler. For VC 6.x this might be found at:
C:\Program Files\Microsoft Visual Studio\VC98\bin\VCVARS32.BAT
Once the environment is setup, you can cd to the GDAL root directory and do the following:
C:\GDAL> nmake /f makefile.vc
Once the build has completed successfully, you can also install the required GDAL files for using GDAL utilities using the install makefile target. Ensure that BINDIR, and DATADIR are set appropriately in the nmake.opt file before doing this.
C:\GDAL> nmake /f makefile.vc install
If you wish to build your own applications using GDAL you can use the following command to install all the required libraries, and include files as well. Ensure that LIBDIR and INCDIR are properly set in the nmake.opt file.
C:\GDAL> nmake /f makefile.vc devinstall
Projects linking against GDAL should include the directory specified in INCDIR in the include path, and the directory specified in LIBDIR in their /LIBPATH. To use gdal link against the gdal_i.lib stub library.
Basic Options
There are lots of options that can be tweaked by hand in the nmake.opt file in the GDAL root directory.
-
BINDIR: Directory in which to install executables, and DLLs if you use the "nmake /f makefile.vc install" command.
-
LIBDIR: Directory in which to install stub library (gdal_i.lib).
-
INCDIR: Directory in which to install GDAL/OGR include files.
-
DATADIR: Directory in which to install GDAL required data files.
-
OPTFLAGS: Set this to contain the desired compiler flags for compiling. The default is a debug build but there is usually a suitable alternative for optimized builds commented out in the template file. Please, note that if you will build GDAL against the third-party libraries (installed from precompiled binaries or compiled by yourself) you should keep the run-time linking options for that libraries and for GDAL the same. For example, if you will use /MD option in OPTFLAGS string (link against multithreaded dynamic library), the same should be used to build other libraries, such as HDF4 or JasPer. If you don't have library sources then read the documentation, supplied with library, to figure out how it was compiled and set up the same linking option in OPTFLAGS. Mixing different linking options or release/debug flags will result in build failures or in crashes during run time.
Advanced Options
-
PY_INST_DIR: Directory to install python modules in. Only required if Python support is being built.
-
PYDIR: The directory where your python tree is installed. Used to find python include files. If this is set to a directory that does not exist then python support will be omitted from the build.
-
DLLBUILD: Define this (to "1") to force all the OGR utilities to link against the GDAL DLL instead of building built statically.
-
INCLUDE_OGR_FRMTS: Set to "YES" to build OGR formats into the GDAL dll, or comment out to omit OGR formats from build.
-
SETARGV: Point this to the setargv.obj file distributed with Visual Studio to get wildcard expanasion for commandline arguments or leave commented out to omit this.
-
ECWDIR/ECWLIB: Uncomment these to enable building with ECW support, correcting ECWDIR to point to the install location on your system.
-
OGDIDIR/OGDIVER/OGDILIB: Uncomment these to enable OGDI support, correcting the OGDIDIR and OGDIVER values as needed.
-
HDF4_DIR: Uncomment, and correct path to enable support for NCSA HDF Release 4.
-
JASPER_DIR/JASPER_INCLUDE/JASPER_LIB: This variables should be pointed to appropriate directories where JasPer library was installed. JasPer toolkit needed for JPEG2000 support.
-
XERCES_DIR/XERCES_INCLUDE/XERCES_LIB: Uncomment these and correct XERCES_DIR to enable Xerces XML parser support for GML read support.
-
FME_DIR: Uncomment, and correct path to enable support for FMEObject vector access.
-
JPEG_EXTERNAL_LIB/JPEGDIR/JPEG_LIB: Used to be able to link gdal with an external JPEG library. Uncomment these lines and correct the paths.
-
PNG_EXTERNAL_LIB/PNGDIR/PNG_LIB: Used to be able to link gdal with an external PNG library. Uncomment these lines and correct the paths.
I frequently forget to update the Windows makefiles when I add new files, so if something comes up missing consider comparing the file lists in the appropriate makefile.vc against the GNUmakefile or just contact me.
External Libraries
Several drivers require additional libraries to be installed in your system. These are:
-
NCSA HDF library can be downloaded from the The NCSA HDF Home Page at the National Center for Supercomputing Applications.
If your OS distribution already contains prebuilded HDF library you can use one from the distribution.
Please note, that NCSA HDF library compiled with several defaults which is defined in hlimits.h file. For example, hlimits.h defines the maximum number of opened files:
# define MAX_FILE 32
If you need open more HDF4 files simultaneously you should change this value and rebuild HDF4 library (there is no need to rebuild GDAL if it is already compiled with HDF4 support).
-
JPEG2000 support based on JasPer toolkit which can be accessed from the The JasPer Project Home Page.
JasPer itself is a bridge for working with several image file formats. Only JP2 and JPC parts of JasPer used in GDAL.
You need modified JasPer library to build this driver with GeoJP2 support enabled. Modified version can be downloaded from ftp://ftp.remotesensing.org/gdal/jasper-1.701.0.uuid.tar.gz
-
MrSID driver needs LizardTech decoding software development kit (DSDK). This DSDK is not free software, you should contact LizardTech to obtain it. DSDK distributed in binary form and if you are using GCC, please, ensure that you have the same compiler as was used for DSDK compilation. It is C++ library, so you may get incompatibilities in C++ name mangling between different GCC versions (2.95.x and 3.x).
-
NetCDF support requires the netCDF library. Once it is built and installed, use the "--with-netcdf=<path to install tree>" option to configure and build GDAL. Link conflicts have been observed with the netCDF libraries, and the HDF libraries ... coexistance may not be practical. NetCDF support has not been built or tested on Windows.
Large File Support
GDAL supports reading and writing large files (> 2GiB) if it is possible in your operating system. Notes about large file support on Linux available here: http://www.suse.de/~aj/linux_lfs.html. In short: if you have kernel 2.4.x and glibc 2.2.x you are in luck. Maximum file size depends on cluster size. For ext2 filesystem with 1 KiB clusters it is 16448 MiB, for ext2 with 4 KiB clusters it is 2048 GiB. Other filesystems can handle even larger files.
Information about large file support in Windows could be obtained at MSDN. In short, maximum file size at NTFS is limited by (2^64 - 1) bytes, at FAT32 and FAT16 it is (2^32 - 1) bytes. So don't try create files larger than 4 GiB on FAT32. In some cases you will not get an error message during jumping over 4GiB barrier, but all your data will be lost. This is not a GDAL bug, this is Windows problem.
Generated on Mon Jan 9 18:03:36 2006 for GDAL by
1.4.6