218 lines
6.4 KiB
Markdown
218 lines
6.4 KiB
Markdown
# Osmium Library
|
|
|
|
http://osmcode.org/libosmium
|
|
|
|
A fast and flexible C++ library for working with OpenStreetMap data.
|
|
|
|
NOTE: This is a beta version of the next-generation Osmium. For production
|
|
use, see the Osmium version at https://github.com/joto/osmium .
|
|
|
|
There are a few applications that use the Osmium library in the examples
|
|
directory. See the [osmium-contrib](http://github.com/osmcode/osmium-contrib)
|
|
repository for more example code.
|
|
|
|
[](http://travis-ci.org/osmcode/libosmium)
|
|
[](https://ci.appveyor.com/project/Mapbox/libosmium)
|
|
|
|
Libosmium is developed on Linux, but also works on OSX and Windows (with some
|
|
limitations).
|
|
|
|
## Prerequisites
|
|
|
|
Because Osmium uses many C++11 features you need a modern compiler and standard
|
|
C++ library. Osmium needs at least GCC 4.8 or clang (LLVM) 3.2. (Some parts may
|
|
work with older versions.)
|
|
|
|
Different parts of Osmium (and the applications built on top of it) need
|
|
different libraries. You DO NOT NEED to install all of them, just install those
|
|
you need for the programs you need.
|
|
|
|
boost-iterator, boost-regex
|
|
http://www.boost.org/
|
|
Debian/Ubuntu: libboost-dev
|
|
openSUSE: boost-devel
|
|
Homebrew: boost
|
|
|
|
boost-program-options (for parsing command line options in some examples)
|
|
http://www.boost.org/doc/libs/1_54_0/doc/html/program_options.html
|
|
Debian/Ubuntu: libboost-program-options-dev
|
|
|
|
Google protocol buffers (for PBF support)
|
|
http://code.google.com/p/protobuf/ (at least version 2.3.0 needed)
|
|
Debian/Ubuntu: libprotobuf-dev protobuf-compiler
|
|
openSUSE: protobuf-devel
|
|
Homebrew: protobuf
|
|
Also see http://wiki.openstreetmap.org/wiki/PBF_Format
|
|
|
|
OSMPBF (for PBF support)
|
|
https://github.com/scrosby/OSM-binary
|
|
Debian/Ubuntu: libosmpbf-dev
|
|
(The package in Ubuntu 14.04 and older is too old, install from source
|
|
in these cases.)
|
|
Homebrew: osm-pbf
|
|
|
|
Expat (for parsing XML files)
|
|
http://expat.sourceforge.net/
|
|
Debian/Ubuntu: libexpat1-dev
|
|
openSUSE: libexpat-devel
|
|
Homebrew: expat
|
|
|
|
zlib (for PBF and for gzip support when reading/writing XML)
|
|
http://www.zlib.net/
|
|
Debian/Ubuntu: zlib1g-dev
|
|
openSUSE: zlib-devel
|
|
|
|
bz2lib (for bzip2 support when reading/writing XML)
|
|
http://www.bzip.org/
|
|
Debian/Ubuntu: libbz2-dev
|
|
|
|
Google sparsehash
|
|
http://code.google.com/p/google-sparsehash/
|
|
Debian/Ubuntu: libsparsehash-dev
|
|
openSUSE: sparsehash
|
|
Homebrew: google-sparsehash
|
|
|
|
GDAL (for OGR support)
|
|
http://gdal.org/
|
|
Debian/Ubuntu: libgdal1-dev
|
|
openSUSE: libgdal-devel
|
|
Homebrew: gdal
|
|
|
|
GEOS (for GEOS support)
|
|
http://trac.osgeo.org/geos/
|
|
Debian/Ubuntu: libgeos++-dev
|
|
openSUSE: libgeos-devel
|
|
Homebrew: geos
|
|
|
|
libproj (for projection support)
|
|
http://trac.osgeo.org/proj/
|
|
Debian/Ubuntu: libproj-dev
|
|
|
|
Doxygen (to build API documentation) and tools
|
|
http://www.stack.nl/~dimitri/doxygen/
|
|
Debian/Ubuntu: doxygen graphviz xmlstarlet
|
|
Homebrew: doxygen
|
|
|
|
You need to either install the packages for your distribution or install those
|
|
libraries from source. Most libraries should be available in all distributions.
|
|
|
|
|
|
## Directories
|
|
|
|
* include: C/C++ include files. All of Osmium is in those header files which
|
|
are needed for building Osmium applications.
|
|
|
|
* examples: Osmium example applications.
|
|
|
|
* test: Tests (see below).
|
|
|
|
* doc: Config for documentation.
|
|
|
|
|
|
## Building
|
|
|
|
Osmium is a header-only library, so there is nothing to build for the
|
|
library itself.
|
|
|
|
But there are some tests and examples that can be build. Libosmium uses
|
|
cmake:
|
|
|
|
mkdir build
|
|
cd build
|
|
cmake ..
|
|
make
|
|
|
|
This will build the examples and tests. Call `ctest` to run the tests.
|
|
|
|
To build the documentation you need Doxygen. If cmake can find it it will
|
|
enable the `doc` target so you can build the documentation like this:
|
|
|
|
make doc
|
|
|
|
If the 'cppcheck' binary is found, cmake will add another target to the
|
|
Makfile which allows you to call cppheck on all `*.cpp` and `*.hpp` files:
|
|
|
|
make cppcheck
|
|
|
|
For Mac users: If you have clang 3.2 or newer, use the system compiler.
|
|
If not you have to build the compiler yourself. See the instructions
|
|
on http://clang.llvm.org/ .
|
|
|
|
Preliminary support for cmake is provided. You can use this instead of "make":
|
|
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
There are a few unit tests using the Catch unit test framework in the "test"
|
|
directory. Many more tests are needed, any help appreciated.
|
|
|
|
For [Catch](https://github.com/philsquared/Catch/) only one header file is
|
|
needed which is included (`test/include/catch.hpp`).
|
|
|
|
To compile these unit tests make sure `BUILD_UNIT_TESTS` is set in the cmake
|
|
config, then build the project and call
|
|
|
|
ctest
|
|
|
|
You can run tests matching a pattern by calling
|
|
|
|
ctest -R test_name
|
|
|
|
for instance:
|
|
|
|
ctest basic_test_node
|
|
|
|
will run the `basic_test_node` and `basic_test_node_ref` tests.
|
|
|
|
### Data Tests
|
|
|
|
In addition there are some test based on the OSM Test Data Repository at
|
|
http://osmcode.org/osm-testdata/ . Make sure `BUILD_DATA_TESTS` is set in the
|
|
cmake config, then build the project and call `ctest`.
|
|
|
|
Some of these tests need Ruby and then 'json' gem installed.
|
|
|
|
### Valgrind
|
|
|
|
Running tests with valgrind:
|
|
|
|
ctest -D ExperimentalMemCheck
|
|
|
|
|
|
## Osmium on 32bit Machines
|
|
|
|
Osmium works well on 64 bit machines, but on 32 bit machines there are some
|
|
problems. Be aware that not everything will work on 32 bit architectures.
|
|
This is mostly due to the 64 bit needed for node IDs. Also Osmium hasn't been
|
|
tested well on 32 bit systems. Here are some issues you might run into:
|
|
|
|
* Google Sparsehash does not work on 32 bit machines in our use case.
|
|
* The `mmap` system call is called with a `size_t` argument, so it can't
|
|
give you more than 4GByte of memory on 32 bit systems. This might be a
|
|
problem.
|
|
|
|
Please report any issues you have and we might be able to solve them.
|
|
|
|
|
|
## Switching from the old Osmium
|
|
|
|
See `README-changes-from-old-osmium`.
|
|
|
|
|
|
## License
|
|
|
|
The Osmium Library is available under the Boost Software License. See
|
|
LICENSE.txt.
|
|
|
|
|
|
## Authors
|
|
|
|
The Osmium Library was mainly written and is maintained by Jochen Topf
|
|
(jochen@topf.org).
|
|
|
|
Other authors:
|
|
* Peter Körner (github@mazdermind.de) (PBF writer, ...)
|
|
|