History

Note: This page is deprecated now! Please visit the Build Guide for the canonical resource on building QGIS from source.

Motivation of using CMake instead of popular Automake+Autoconf build system lies on being able to achieve many build tasks better. Here are the main benefits:
  • cross-platform: works well on Linux (and other UNIXes), Mac OS X and Windows
  • simpler syntax, easier to learn
  • faster build times
  • nice build output with progress and colors ;-)

Autotools have the advantage that they're far more widespread and users know very well the usual

./configure && make && make install

installation. This page tries to introduce CMake system to QGIS users that want build QGIS from source. It doesn't go much to details so if you're interested in further knowledge, seek for more information on home page: http://www.cmake.org/

CMake installation

To install CMake, download it from http://www.cmake.org/HTML/Download.html for your platform or use your distribution's packages. Building CMake from source shouldn't be a problem, the only dependency is a C++ compiler.

Note: Use CMake version 2.4.3 or later!

Simple build

To start configuration and generation of makefiles, go to source directory and run:

 cmake .
 make
 make install

The dot means that it should use current directory as a root of the build. If configuration will end without errors CMake will also generate makefiles, otherwise it will show some errors. The problems usually lie in not being able to set some variables automatically - in that case you can specify them manually.

QGIS application binary is compiled currently only using main.cpp file (in src/gui/ dir) and everything is linked as shared libraries - e.g. for GEOS you would set GEOS_INCLUDE_DIR and GEOS_LIBRARY.

Out-of-source build

This build option is good especially for developers as it allows building several different configurations with the same sources. E.g. you can build either debug / release version, use dynamic / static linking and more options. To use out-of-source build just create a directory where it will get built - nothing complicated:

 mkdir build
 cd build
 cmake ..
 make
 make install

Another benefit is that it's easy to delete the whole build just by deleting its directory.

Configuration

All configuration settings are variables. You can set them manually in two different ways:

  • specifying on command line:
 cmake -D VAR1=VALUE1 -D VAR2=VALUE2 ...
  • using an interactive tool
    • Windows: cmakesetup - tool providing a dialog for configuration
    • UNIX/Mac OS: ccmake - ncurses based configuration tool. You need to specify path for these tools what build do you want to configure

Important variables

There are several variables that you might want to set:

Variable
Default value
Meaning
CMAKE_INSTALL_PREFIX
/usr/local prefix where to install application and its data
CMAKE_BUILD_TYPE
whether to compile with debugging support or not (values Release or Debug)
CMAKE_SKIP_RPATH * OFF turning this ON will save you some compile time as relinking during 'make install' won't happen

|
QGIS specific variables:

Variable
Default value
Meaning
QT_QMAKE_EXECUTABLE
Path to Qt4 qmake - detected automatically when in usual location
WITH_BINDINGS TRUE whether it should try to build Python bindings for QGIS
WITH_GRASS TRUE whether it should try to build GRASS plugin
GRASS_PREFIX
/usr/lib/grass path to GRASS installation
BINDINGS_GLOBAL_INSTALL FALSE whether bindings should be installed to global python directory (might need to be root)
PEDANTIC TRUE whether compiler warnings should be considered as errors

|
Variables marked with * are advanced - this means that they're not shown by default in CMake GUI (ccmake or cmakesetup), however it's possible to show them.

Also if you have your libraries in non-standard locations you'll probably will need to specify their include directory and library file.

Platform specific notes

Unix notes

If you have all dependencies in standard paths (/usr or /usr/local), configuration should be done without any problems.

It should be possible to generate KDevelop3 project files with "KDevelop3" generator.

Windows notes

Notes for compilation on Windows (with MinGW compiler) can be found here:

http://svn.qgis.org/trac/browser/trunk/qgis/README_windows.txt

If you intend to use Visual C++ for building QGIS, make sure to compile also at least C++ dependencies (Qt, GDAL, GEOS) with Visual C++ because MinGW and VC++ use different decoration for symbols for C++ code. C libraries should work fine.

Mac OS X notes

For detailed guide see Installation Guide

Troubleshooting

In case that something goes wrong and build fails, it's useful to see the actual commands being run by 'make' to find out what's wrong. This is how to do it:

 make VERBOSE=1

This sections lists some additional materials about CMake: