Up until 0.17, Merkaartor had no "hard" (as in "cannot compile without") dependencies. Merkaartor could be compiled and used with only Qt.
However, as of 0.18, Merkaartor has a number of "hard" dependencies:

  • PROJ.4, the indispensable library for all projections related stuff (>= 4.6)
  • GDAL, the indispensable library for all gis-related file formats (>=1.6.0)

Linux users willing to compile Merkaartor from sources, that mean installing those packages:

For Ubuntu/Debian
  • libproj0 and libproj-dev
  • libgdal1 and libgdal-dev
For Fedora
  • proj-devel
  • gdal-devel

For Qt < 4.7
A clipping issue in Qt versions < 4.7 make also installing Boost (>= 1.38) a requirement. As of Qt >= 4.7, this is not needed.

  • libboost-dev
  • boost-devel


In order for the plugins to be available, the build has to be installed via

make install


A number of optional components/features can be added to Merkaartor that require more external dependencies and their enabling via the qmake command line:

qmake parameter dependency description
GEOIMAGE=1 libexiv2, libexiv2-dev enable geotagged images
ZBAR=1 libzbar0, libzbarqt0, libzbar-dev, libzbarqt-dev (>=0.10) use the ZBAR library to extract coordinates from barcode for the "Walking Paper" plugin
LIBPROXY=1 libproxy0, libproxy-dev use the libproxy library to automatically detect the system proxy
GPSDLIB=1 libgps, libgps-dev (>=2.92) use gpsd for GPS readings

Other qmake options

Other options can be specified to tune the result

qmake parameter description
PREFIX=<path> base prefix for installation (default: /usr/local)
LIBDIR=<path> base directory for plugins (default: $$PREFIX/lib)
PORTABLE=1 build merkaartor as a portable app (all files in app dir)
TRANSDIR_MERKAARTOR=<path> translations directory for merkaartor.
Beware: The translations "executables" (i.e. *.qm") must exist before running qmake for them to be picked up for installation in Unix.
lrelease src/
TRANSDIR_SYSTEM=<path> translations directory for Qt itself
NODEBUG=1 no debug target
RELEASE=1 indicates a release version (cosmetic); to be used with NODEBUG=1
NVIDIA_HACK=1 used to solve NVidia specific slowdown
NOUSEWEBKIT=1 Disable Webkit (used for the Yahoo plugin). Only meaninful it you don't have Qt Webkit installed for some reason

Typical qmake command line

A typical qmake command line to build a full blown debug merkaartor without automatic proxy support installing in /usr/local would be


Problems running qmake

If you get some errors like "WARNING: Found potential symbol conflict of ..." when running qmake, your qmake is probably using qt3. Try to start qmake with qt4:

qmake-qt4 -r <...>

Linux quick start

Make sure the necessary software is installed: # For Debian or Ubuntu based systems:
sudo apt-get install git libqt4-dev qt4-qmake gcc g++ zlib1g-dev \
libexiv2-dev libgdal1-dev libxml2-dev libxslt1-dev libboost-dev \
libboost-math-dev libboost-serialization-dev libproj-dev

  1. For Fedora:
    yum install git qt-devel gcc-c++ zlib-devel exiv2-devel gdal-devel \
    libxml2-devel libxslt-devel boost-devel boost-math boost-serialization

Get the latest development snapshot:
git clone git://

Change directory and compile:
cd main

Add NOUSEWEBKIT=1 to qmake if you are using a version of Qt below 4.4.0 or do not have QWebkit compiled in.

Test the binary:

Note: In order for plugins (such as Yahoo! Aerial Imagery or Walking Papers) to be available when running Merkaartor, the Merkaartor binaries must be installed as well:
make install

If there are no plugins available try installing qtwebkit development packages, libspatialite, libgdal (see top of page), libdap, and their dependencies.

Building on Mac OS X

  • XCode
  • QT

You can obtain Xcode form your Mac OSX Installation DVD or you can download it from:

Download QT from:
If on 10.4 choose the Carbon version, on 10.5 and newer choose the Cocoa version

Additional libraries (GDAL, Geoimage, libspatialite) can be easily compiled using either:
Homebrew (
Macports (
Fink (
Direct from source

Now that you have all that is needed you can obtain the desired version of merkaartor (either via git or source download)
qmake -r -spec macx-g++

How to build Merkaartor on Windows (outdated)

To build Merkaartor on Windows, you need:

How to build Merkaartor on Windows (outdated)

This describes how to build Merkaartor from source, with Qt 4.5, MinGW and Windows. The entire procedure will take about half an hour to an hour, depending on your CPU speed, internet link and wizardry skills. You should probably not do this in VMware. It'll work, but oddly things take four times as long.

Note: There are several external dependencies to libraries that need to be built before Merkaartor can be built. This How To includes all dependencies. You can possibly take a shortcut on that using the prebuilt dependencies for MinGW available on gitorious:

In the the merkaartor source directory, run:

git clone binaries

to get them.



  • Qt
    : Target directory for MinGW: C:\MinGW
    : Be sure MinGW is installed before you proceed. Should Qt fail to install MinGW, you can get the [ Automated MinGW Installer] at SourceForge. Select the following components to install:
    :* MinGW base tools
    :* g++ compiler
    :* MinGW Make
    : All components are downloaded through the installer. If one fails to download, SourceForge has a bad mirror; just click on "Retry" until it works.
  • MSYS
    : Target directory: C:\MSYS (I suggest you leave out the version number)
    : Post installation configuration:
    :: Do you wish to continue with the post install? [yn ] y
    :: Do you have MinGW installed? [yn ] y
    *:: Where is your MinGW installation? c:/mingw
  • optionally: TortoiseSVN (Windows restart required)

Unpack downloaded archives

In this how-to, the development root directory is <font color=brown>Z:\dev</font>. Its MSYS equivalent is <font color=brown>/z/dev</font>. Whereever you see them here, change them to your local paths.

  • zlib -> <font color=brown>z:\dev</font>\zlib
  • libexpat -> <font color=brown>z:\dev</font>\expat (strip top-level archive directory)
  • exiv2 -> <font color=brown>z:\dev</font>\exiv2 (strip top-level archive directory)
  • Merkaartor -> <font color=brown>z:\dev</font>\merkaartor
  • optionally: SVN binaries -> <font color=brown>z:\dev</font>\svn (no subdirectory, put svn.exe right in here)

Build the libraries

All following lines in the box are meant to be typed into the '''MSYS shell''' (find it in your start menu).

Build zlib:
cd <font color=brown>/z/dev</font>
cd zlib
mkdir include lib
cp z{lib,conf}.h include
cp libz.a lib
cd ..

Build libexpat:
cd expat
mkdir include
cp lib/expat{,_external}.h include
cp .libs/libexpat.a lib/libexpat.a
cd ..

Build exiv2:
cd exiv2
./configure --with-zlib=$mypath/zlib --with-expat=$mypath/expat --disable-shared
mkdir include include/exiv2 lib
cp src/*.h{,pp} include/exiv2
cp src/.libs/libexiv2.a lib
cd ..

All following lines in the box are meant to be typed at the '''Qt command prompt''' (find it in your start menu).

Optionally download the latest SVN source of Merkaartor: (This will download all source files into the merkaartor subdirectory. You better rename it if you already have one.)
cd /d <font color=brown>z:\dev</font>
svn\svn co

Build Merkaartor

Edit the file src\Custom.pri in Merkaartor's directory and add the following contents:

  1. This fixed a bug in earlier Qt (4.4.3) together with earlier MinGW's winbase.h.
  2. It is not required anymore in current version.
  1. Add more search paths for libraries and include files.
    LIBS += -L$$PWD/../../exiv2/lib -L$$PWD/../../expat/lib -lexiv2 -lexpat
    INCLUDEPATH += $$PWD/../../exiv2/include
  2. The paths are specific to our build setup.
  3. -lexpat was forgotten in Merkaartor's Makefile.
  4. -lexiv2 must occur before -lexpat! Since the original Makefile doesn't do
  5. that, we add it again in the required order.
  1. Enable support for geo-tagged images, we meet all requirements.
  1. Add more qmake options here if you like.
  2. See Config.pri or for a reference.

Still in the Qt command prompt...

cd /d &lt;font color=brown&gt;z:\dev&lt;/font&gt;
cd merkaartor
qmake -r NODEBUG=1

In case you need a '''debug''' build, leave away the parameter "NODEBUG=1".

Should the make command not be found, you can try mingw32-make instead.

Now build the translation files in a separate step:

cd translations
make release
cd ..

Copy dependency files

Now copy all Merkaartor and Qt translations, DLLs and the binary into a new directory:
mkdir output
copy "binaries\win32-g++\bin\merkaartor.exe" output
mkdir output\plugins
xcopy /s "binaries\win32-g++\bin\plugins" output\plugins
copy translations\*.qm output
mkdir output\translations
copy QTDIR\translations\qt_??.qm output\translations
copy QTDIR\translations\qt_??_??.qm output\translations
copy QTDIR\bin\mingwm10.dll output
(If the last file doesn't exist, go look for it where you have installed MinGW to, e.g. C:\MinGW\bin, and also copy it to the specified Qt\bin directory, since Qt tools will also need this DLL.)
mkdir output\imageformats
copy QTDIR\plugins\imageformats\qico4.dll output\imageformats
copy QTDIR\plugins\imageformats\qtiff4.dll output\imageformats\qtif4.dll
copy QTDIR\plugins\imageformats\qsvg4.dll output\imageformats
copy QTDIR\plugins\imageformats\qgif4.dll output\imageformats
copy QTDIR\plugins\imageformats\qjpeg4.dll output\imageformats
If you've built a '''release''' executable, use these files:
copy QTDIR\bin\QtWebKit4.dll output
copy QTDIR\bin\QtSvg4.dll output
copy QTDIR\bin\QtGui4.dll output
copy QTDIR\bin\QtNetwork4.dll output
copy QTDIR\bin\QtXml4.dll output
copy QTDIR\bin\QtCore4.dll output
If you've built a '''debug''' executable, use these files:
copy QTDIR\bin\QtWebKitd4.dll output
copy QTDIR\bin\QtSvgd4.dll output
copy QTDIR\bin\QtGuid4.dll output
copy QTDIR\bin\QtNetworkd4.dll output
copy QTDIR\bin\QtXmld4.dll output
copy QTDIR\bin\QtCored4.dll output

You can now execute Merkaartor.exe in the directory output.