Building with CMake - Quantum GIS Wiki

$/!\$ Note: This page is deprecated now! Please visit BuildingFromSource for the canonical resource on building QGIS from source.

Contents

Introduction
CMake installation
Simple build
Out-of-source build
Configuration
Important variables
Platform specific notes
Troubleshooting
Links

Introduction

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 markerd 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 BuildingOnMacOsX

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