Building and Installing libkml

Please read the DEPENDENCIES file carefully and ensure you have the correct versions of all required software.

There are two separate build systems: one for GNU/Linux and Mac OS X, and another for Microsoft Windows.

This is lasted upated for version 0.3.0. There may be changes within the svn tree.

Linux and Mac OS X

We assume you have a reasonable GCC/autotools environment installation. Performing a basic build should be as simple as:

cd libkml-0.x.x
mkdir build
cd build
../configure
make
sudo make install

In addition to the usual GNU build system configure options like --prefix, you may fine-tune the building of libkml as follows. (Use ./configure --help to see all extra options.)

SWIG bindings

If you want to create bindings for the additional supported languages, you need to install the Simplified Wrapper and Interface Generator (SWIG) version 1.3.35.

NOTE: the Microsoft Windows Visual Studio .vcproj's do not build SWIG.

Once SWIG is installed, the configure program will check for the existence of development versions of Python and Java. If either is found, we attempt to build the SWIG bindings. If you have either language installed in a non-default location, you can specify the location(s) of your headers and libs like so:

../configure --with-java-include-dir=DIR \
             --with-java-lib-dir=DIR \
             --with-python-include-dir=DIR \
             --with-python-lib-dir=DIR

It is likely that the Python installation and headers will be discovered automatically. If you want to build the Java bindings you will almost certainly have to tell configure where to find the headers it needs.

For Mac OS X the command is probably quite close to this:

../configure --with-java-include-dir=/System/Library/Frameworks/JavaVM.framework/Headers

For Linux is it is something like:

../configure --with-java-include-dir=/usr/lib/jvm/include

If possible, SWIG bindings are always built. You can disable this by:

../configure --disable-swig

Or you can disable specific languages:

../configure --disable-java --disable-python

By default we do not install the Python SWIG bindings in the system Python extension directory. This is because writing to that directory likely requires root privileges. You can override this behavior as follows. Installation must then be performed by sudo make install.

../configure --enable-systempython

Otherwise, the Python bindings will be installed to a directory relative to configure's prefix. This will likely be similar to /usr/local/lib/python2.5/site-packages/. Your PYTHONPATH will of course have to know about this directory.

Microsoft Windows XP

We have used Microsoft Visual Studio 2005 to create the project files. The top-level libkml.sln is the main solution file and will build all libraries in the libkml system. You can also build the examples from the solution file in the examples directory.

(It is known that Microsoft Visual Studio 2008 does not work with libkml)

Running the unit tests

It is HIGHLY recommended that you build and run all unit tests. We consider the unit tests of libkml as important as the code itself given these assert semantics about the KML language itself and not just the libkml system. You will note that the unit tests for a given module often far exceed that module in raw lines of code.

NOTE: the Microsoft Visual Studio .vcproj's have no knowledge of these tests.

Build cppunit without RTTI

Since libkml does not use RTTI, you must configure cppunit accordingly.

On Mac OS X the command is:

./configure --disable-typeinfo-name

On Linux the command is:

./configure --disable-typeinfo-name LIBS="-ldl"

See the top-level DEPENDENCIES file.

Build and run the libkml unit tests

We have provided a large suite of unit tests to verify the correct behavior of libkml. We use the CppUnit framework. If you have installed cppunit in its default location (a prefix of /usr/local) the existence of such should be discovered automatically. If you have a custom installation, you can specify where the headers and libraries are installed as:

../configure --with-cppunit-prefix=PFX --with-cppunit-exec-prefix=PFX

You can run the tests like so:

make check

Excerpts of the test output as of 0.3.0 looks as follows.

In reporting any problem with libkml please also submit a complete trace of your run of the unit test suite.

...
Making check in base
...
make  check-TESTS
FileTest::TestReadFileToString : OK
FileTest::TestWriteStringToFile : OK
FileTest::TestExists : OK
FileTest::TestDelete : OK
FileTest::TestCreateNewTempFile : OK
OK (5)
PASS: file_test
ReferentTest::TestReferent : OK
ReferentTest::TestIntrusivePointerFunctions : OK
ReferentTest::TestDelete : OK
ReferentTest::TestVector : OK
ReferentTest::TestFunc : OK
ReferentTest::TestBasicParentChild : OK
ReferentTest::TestGetChild : OK
OK (7)
PASS: referent_test
TempFileTest::TestTempFile : OK
OK (1)
PASS: tempfile_test
==================
All 3 tests passed
==================
Making check in convenience
...
make  check-TESTS
CsvFileTest::TestEmpty : OK
CsvFileTest::TestSplitStringUsing : OK
CsvFileTest::TestParseCsvLine : OK
CsvFileTest::TestParseCsvFile : OK
OK (4)
PASS: csv_file_test
ConvenienceTest::TestCreatePointPlacemark : OK
ConvenienceTest::TestCreateRegion2d : OK
OK (2)
PASS: convenience_test
KmzCheckLinksTest::TestNoLinks : OK
KmzCheckLinksTest::TestNull : OK
KmzCheckLinksTest::TestOverlay : OK
KmzCheckLinksTest::TestBadOverlay : OK
OK (4)
PASS: kmz_check_links_test
FeatureListTest::TestDefault : OK
FeatureListTest::TestSave : OK
FeatureListTest::TestNull : OK
FeatureListTest::TestPushBack : OK
FeatureListTest::TestRegionSplitAll : OK
FeatureListTest::TestRegionSplitSome : OK
FeatureListTest::TestRegionSplitIncrementally : OK
OK (7)
PASS: feature_list_test
==================
All 4 tests passed
==================
Making check in dom
...
creating xsd_test
make  check-TESTS
AbstractLatLonBoxTest::TestType : OK
AbstractLatLonBoxTest::TestDefaults : OK
AbstractLatLonBoxTest::TestSetToDefaultValues : OK
AbstractLatLonBoxTest::TestSetGetHasClear : OK
OK (4)
PASS: abstractlatlonbox_test
...
PASS: xml_serializer_test
XsdTest::TestGoodElement : OK
XsdTest::TestBadElement : OK
XsdTest::TestUglyElement : OK
XsdTest::TestGoodEnum : OK
XsdTest::TestBadEnum : OK
XsdTest::TestUglyEnum : OK
OK (6)
PASS: xsd_test
===================
All 43 tests passed
===================
Making check in engine
...
make  check-TESTS
KmlFileTest::TestInitialState : OK
KmlFileTest::TestEncoding : OK
KmlFileTest::TestBasicParseFromString : OK
KmlFileTest::TestRoot : OK
KmlFileTest::TestBasicObjectIdParse : OK
KmlFileTest::TestObjectIdDupe : OK
KmlFileTest::TestObjectIdMapReplaced : OK
KmlFileTest::TestNullGetSharedStyleById : OK
KmlFileTest::TestBasicGetSharedStyleById : OK
KmlFileTest::TestReparse : OK
OK (10)
...
StyleResolverTest::TestFiles : OK
OK (1)
PASS: style_resolver_test
===================
All 14 tests passed
===================
Making check in regionator
...
FeatureListRegionHandlerTest::TestBasic : OK
OK (1)
PASS: feature_list_region_handler_test
RegionatorTest::TwoLevelPointRegionatorTest : OK
RegionatorTest::FourLevelPointRegionatorTest : OK
OK (2)
PASS: regionator_test
...
PASS: regionator_util_test
==================
All 4 tests passed
==================

Some amount of Python SWIG functionality is tested in src/swig/kmldom_test.py. A successful run of this test looks as follows:

.......................................
----------------------------------------------------------------------
Ran 39 tests in 0.013s

OK

And so on. If any tests fail to pass, you will be asked to report the issue to this project's issue tracker.