QGIS Xcode Project

2.6.1	2010-9-26

About

This builds QGIS, as an alternative to the CLI Unix build (both build the Mac application).  By default everything is built for the native architecture.

Dependent libraries are optionally copied into the application bundle and embedded library paths are adjusted.  Some dependent libraries are always copied for stability reasons (Qt, PyQt).

Requirements

See the Qgis installation document for details on obtaining the requirements.  All optional items below are required for the default Full QGIS build target.

Xcode 2.5 (minimum) - This also makes Mac OS 10.4 a minimum requirement.

QGIS source

Qt 4.4+ frameworks - install debug version if desired (may require a separate installer download).  At least Qt Cocoa 4.6 is needed on Snow Leopard for a 64bit build.

GDAL library or framework - a universal GDAL.framework is available.

PROJ library or framework - a universal PROJ.framework is available.

GEOS library or framework - a universal GEOS.framework is available.

GRASS libraries - any 6.x version.  A recent GRASS.app build is best for full GRASS support.  See note below.

GSL library or framework (optional) - a universal GSL.framework is available.

Postgres client library (optional) - normally available in a full Postgres installation.

SQLite3 library - OSX includes SQLite 3, or use a more recent SQLite framework (recommended), or use the internal copy.

Spatialite library - Spatialite is included in the SQLite framework starting with 3.6.11.  Or usethe internal copy (tied to the internal SQLite).

Expat library - Leopard and above includes expat.  The one in X11 should work on Tiger, but I prefer to avoid X11 dependencies.

Fcgi library - Leopard and above includes fcgi.  Must be compiled from source for earlier systems.

Bison - Leopard and above includes bison.  Tiger has an old bison that won't work for QGIS.  See the QGIS install instructions for info about how to compile and install this on Tiger.

gpsbabel (optional) - for the GPS Import plugin.  A universal gpsbabel is available from gpsbabel.org.

Python 2.5 or 2.6 - the system Python on Leopard and Snow Leopard will work.  Or install Python 2.5 from python.org (required for Tiger).

SIP and PyQt - make sure that they fully support the installed Qt version.  Development versions may cause trouble for QGIS.  See the QGIS install instructions for info about how to compile and install these.

[Py]Qwt - Qwt needed for GPS tracking function.  PyQwt used for some 3rd-party plugins.  Since PyQwt installs inside PyQt, it must be bundled along with PyQt.  The PyQwt sources can be used, but extra steps are needed to compile Qwt and PyQwt separately.  See the QGIS install instructions for info about how to compile and install these.

Configuration

Make a copy of the qgis_user-template.xcconfig file, named qgis_user.xcconfig.  You can also reuse a qgis_user.xcconfig from an earlier version, to retain your own configuration, but make sure to check the template for any major changes.  Make sure that the qgis_user.xcconfig exists before opening the project.

It is a plain text file, you can edit it in your favorite text editor before opening the project file, or within Xcode after opening the project.

The xcconfig file is a simple text file with environment variables and values, and comments denoted by //.  Very important: # is not a comment character, and will break the config file if used.

Defaults

The default configuration is for a native build, with the Leopard (10.5) SDK.

GDAL, PROJ, GEOS, GSL and SQLite frameworks are used.  Spatialite is expected in the SQLite framework.  Postgres is expected in default /usr/local builds.  Expat and fcgi are from the system on Leopard and above, and are expected in /usr/local on Tiger.  GRASS support is from a GRASS-6.4.app application.  The python.org Python framework is used on Tiger, and the system Python is used on Leopard and above.

By default, Qt, Qwt and the Postgres client library are bundled in the Qgis application.

Minimal Config

You must set at least SDKSYS to match the system you are building for.  Other defaults will adjust automatically to match the SDK.

For Tiger, you need to set BISON (see below).

Build - At the top are some basic build settings.

SDKSYS tells the project to use the 10.4 (tig), 10.5 (leo) or 10.6 (snow) SDK.  Qgis will build in a subfolder of the build folder - this is handy if you want to build once for each system without overwriting any of them.

Note that there may be linking problems with the SDK for non-system libraries and frameworks.  This is because the linker prefixes everything with the SDKROOT and indirectly linked libraries in non-standard locations (ie /usr/local) may not be found.  If you encounter linking errors, you should add symlinks to the SDKROOT to those locations.

For example, /usr/local:

sudo ln -s /usr/local /Developer/SDKs/MacOSX10.4u.sdk/usr/local

If there are subfolders involved that are not already in the SDK, add them first.  Say you have some libraries in /Users/Shared/unix:

sudo mkdir -p /Developer/SDKs/MacOSX10.4u.sdk/Users/Shared
ln -s /Users/Shared/unix /Developer/SDKs/MacOSX10.4u.sdk/Users/Shared/unix

ARCHS is a list of which architectures to build, the default is a native architecture to match the SDK used.  Uncomment ARCHS if you want a universal build.  This is a space-separated list.

ARCHS_P is a list of which architectures to build for Python, this must match the archs in ARCHS.  Uncomment ARCHS_P for a universal build.  This one is a semicolon-separated list.

Support

QT_PLUGINS_DIR is where the Qt plugins are installed.  QTBIN is where the Qt command-line programs are found.  QT_VER_MAJOR and QT_VER_MINOR are the major.minor version of Qt (currently only major version is used).  QT_DIR is the prefix where the internally-used QtUiTools and QtCLucene headers are found.  QT_DIR_SDK is a workaround for the default location of the QtUiTools and QtCLucene libraries (see the comment for details).  QT_PREFIX_FW is the path where the frameworks are found.

The default is for a binary installation of Qt.  If built from source, you may need to change these (QT_DIR, QT_DIR_SDK will be the same, and QT_PREFIX_FW, QT_PLUGINS_DIR and QTBIN will be dirs off QT_DIR).

BISON is the base path to Bison.  If building on Tiger (not on Leopard for Tiger), a user-built bison 2.3 is required.  Leopard has a usable bison.

GPSBABEL is the full path to the gpsbabel CLI program.  Used for bundling gpsbabel.

Library forms - this is where you tell the project what type of library you have, as many of them are available in framework forms as well as libraries.

Most of them are a choice between 'fw' for framework and 'shared' or 'static' for a library.  See the comments in the xcconfig for details, and other possible choices.

Frameworks are the easiest to configure - just set the option to fw, and all PREFIX, INC and LIB options are set for you.  Frameworks assume either a system framework, or the framework is in /Library/Frameworks.

For library forms, the PREFIX (described later) defaults to /usr/local.  If this is where your libraries are installed, setting the form to shared or static is all that's needed.

The version for Qt, PyQt, GRASS and Python can't be detected by the config file, so make sure these are correct.  Python version default is automatic by the SDKSYS.

See detailed dependency notes below.

Bundle options - Some libraries and programs can be bundled in the Qgis.app package for a more portable Qgis.app.  These are pretty straightforward - yes or no.  At some time I will add more checking logic, but for now be explicit.  Generally, you don't need to bundle frameworks or system libraries.  The logic only checks whether the dynamic library or program exists, so it automatically excludes static libraries and frameworks, but it doesn't check whether it's a system library, so you could end up bundling libsqlite from the system.

Prefixes - If you have unix libraries installed in a location other than /usr/local, the next section is where you can change those.  Make sure to check these for any library forms.

Notes for dependencies

- Postgres - An alternative to bundling Postgres is to build Qgis with a static libpq.  There are shared and static forms in the settings.

- GRASS - GRASS.app must be installed as it was built.  If it was moved or renamed after installation, GRASS support in Qgis won't work.  This goes for building Qgis as well as running it to use full GRASS support.  Also, make sure to set the GRASS version in the config, as this is not detectable.

- Python/SIP/PyQt - this is a complex installation.  Python can be either in the system or separately installed in /Library/Frameworks.  SIP/PyQt has both binary program and Python components.  Programs and Python modules will be installed inside the Python framework for a /Library/Frameworks install.  But the system Python has a user location for Python modules, and programs should be installed elsewhere, like /usr/local/bin (follow the Qgis install instructions for SIP/PyQt).

SIP_INC, PYQT_SIP_DIR and PYQT_SIP_FLAGS are set for a system SIP/PyQt install as described in INSTALL.  They should be adjusted for other configurations.  These can be found by starting Python (the desired Python for the Qgis build) in a Terminal, then:

	import sipconfig
	sipconfig.Configuration().sip_inc_dir
	import PyQt4.pyqtconfig
	PyQt4.pyqtconfig.Configuration().pyqt_sip_dir
	PyQt4.pyqtconfig.Configuration().pyqt_sip_flags

SIP/PyQt utility programs are found with the PYTHON_USRBIN setting.  This is automatic if you follow the Qgis SIP/PyQt install instructions.

- Qwt/PyQwt - Qwt version must be set.

Extra Bundling

Other support items not needed by the standard Qgis build can be bundled for a custom Qgis build: extra plugins, libraries, frameworks, Python modules.  For example, some PyQt-based extra modules (ie Qwt5) are installed inside the PyQt folder, and these won't be found if they are not bundled with the Qgis copy of PyQt.

Duplicate the file bundle-template.sh with the name bundle.sh.  Add needed copy and processing commands to this.  See the comments in bundle.sh for details.  bundle.sh is meant to be reusable, just like qgis_user.xcconfig.

Build Targets

The Full QGIS  target will build Qgis with Python support and all default and optional plugins.

Xcode doesn't have a way to conditionally build targets, just code within sources (with standard macro switches).  It will try to keep building as much as it can after errors.  The last target built is the Qgis application itself, which has all the bundling and cleanup steps.  So, if a dependency is missing for a plugin, it will have errors and fail to build, then the app bundling and cleanup will work with what succeeded.

If recompiling any other target, you should then also recompile the bundle target so the bundling steps do their post-processing, else some internal library paths will be wrong.

Cleaning - to clean the project Clean All.  This actually leaves qgsconfig.h and qgsversion.h in the build folder.

For a complete clean, trash the build folder from the project folder (NOT from the project itself!).

Build Products

When finished building, The final Qgis.app is put in the mac/xcode/build/[SDKSYS]/Release (or /Debug) folder.

Debugging

There are 2 "configurations" - Release and Debug.  Use the Release configuration unless you have a need to debug Qgis.

The Debug configuration will use the debug version of Qt, if installed, but that is not required.  To use the debug Qt frameworks, you must change a setting before starting the debugger: in the Executables section of the left pane of the main project window, select the Qgis item and Get Info.  In the General tab of the info window, select Use debug suffix when loading frameworks.

See the Xcode documentation for more info on using the debugger.

- William Kyngesburye
kyngchaos@kyngchaos.com
http://www.kyngchaos.com/