QGIS/mac/xcode/ReadMe.rtf

{\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf430
{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fnil\fcharset0 Monaco;}
{\colortbl;\red255\green255\blue255;}
\vieww10500\viewh12500\viewkind0
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\qc\pardirnatural

\f0\b\fs36 \cf0 QGIS Xcode Project\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b0\fs24 \cf0 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\i \cf0 2.1.0	2009-2-16\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\i0 \cf0 \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b \cf0 About\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b0 \cf0 \
This builds QGIS, as an alternative to the CLI Unix build (both build the Mac application).  By default everything is built universal for both PPC and Intel.\
\
Dependent libraries are optionally copied into the application bundle and embedded library paths are adjusted.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b \cf0 Requirements\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b0 \cf0 \
See the Qgis installation document for details on obtaining the requirements.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \ul \ulc0 Xcode 2.5\ulnone  - This also makes Mac OS 10.4 a requirement.\
\
\ul QGIS source\ulnone \
\
\ul Qt 4.4 frameworks\ulnone \
\
\ul GDAL library or framework\ulnone  - a universal GDAL.framework is available.\
\
\ul PROJ library or framework\ulnone  - a universal PROJ.framework is available.\
\
\ul GEOS library or framework\ulnone  - a universal GEOS.framework is available.\
\
\ul GRASS libraries\ulnone  - any 6.x version.  A recent GRASS.app build is best for full GRASS support.  
\i See note below.
\i0 \
\
\ul GSL libraries\ulnone  (optional)\
\
\ul Postgres client library\ulnone  (optional) - normally available in a full Postgres installation.\
\
\ul SQLite3 library\ulnone  - OSX includes SQLite 3, or use a more recent SQLite framework.\
\
\ul Expat library\ulnone  - Leopard includes expat.  The one in X11 should work on Tiger, but I prefer to avoid X11 dependencies.\
\
\ul gpsbabel\ulnone  (optional) - for the GPS Import plugin.  A universal gpsbabel is available from gpsbabel.org.\
\
\ul Python 2.5\ulnone  - the system Python on Leopard will work.\
\
\ul SIP\ulnone  and \ul PyQt\ulnone \
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b \cf0 Configuration
\b0 \
\
Make a copy of the 
\f1\fs20 qgis_user-template.xcconfig
\f0\fs24  file, named 
\f1\fs20 qgis_user.xcconfig
\f0\fs24 .  You can also reuse a 
\f1\fs20 qgis_user.xcconfig
\f0\fs24  from an earlier version, to retain your own configuration, but make sure to check the template for any major changes.  
\i Make sure that the qgis_user.xcconfig exists before opening the project.
\i0 \
\
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.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \ul Defaults\
\ulnone \
The default configuration is for the native architecture, without using a system SDK.  GDAL, PROJ, GEOS and SQLite frameworks are used.  Expat, Postgres and GSL are expected in default /usr/local builds.  GRASS support is from a GRASS-6.4.app application.  The python.org Python framework is used, even on Leopard.\
\
By default, Qt, GSL, the Postgres client library are bundled in the Qgis application.\
\
\ul Build\ulnone  - At the top are some basic build settings.\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs20 \cf0 SDKSYS
\f0\fs24  tells the project to use the 10.4 (tig) or 10.5 (leo) SDK.  This will also build Qgis in a subfolder of the build folder - this is handy if you want to build once for Tiger (python.org Python) and once for Leopard (system Python) without overwriting either.\
\
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:\
\

\f1\fs20 sudo ln -s /usr/local /Developer/SDKs/MacOSX10.4u.sdk/usr/local\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f0\fs24 \cf0 \
If there are subfolders involved that are not already in the SDK, add them first.  Say you have some libraries in /Users/Shared/unix:\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs20 \cf0 sudo mkdir -p /Developer/SDKs/MacOSX10.4u.sdk/Users/Shared\
ln -s /Users/Shared/unix /Developer/SDKs/MacOSX10.4u.sdk/Users/Shared/unix
\f0\fs24 \
\

\f1\fs20 ARCHS
\f0\fs24  is a list of which architectures to build, the default is the native arch of your Mac.  Uncomment the universal line if that's what you want.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \ul Misc Support\
\ulnone \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\f1\fs20 \cf0 QTDIR
\f0\fs24  is where the Qt command-line programs are found.  The default is for a binary installation of Qt.  If built from source, you may need to change this.\
\

\f1\fs20 BISON
\f0\fs24  is the base path to Bison.  If building on Tiger (not 
\i on
\i0  Leopard 
\i for
\i0  Tiger), a user-built bison 2.3 is required.  Leopard has a usable bison.\
\

\f1\fs20 GPSBABEL
\f0\fs24  is the full path to the gpsbabel CLI program.  Used for bundling gpsbabel.\
\

\f1\fs20 SIP_system
\f0\fs24  is the full path to the sip program when installed for the system Python on Leopard.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \ul Library forms\ulnone  - 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 
\f1\fs20 fw
\f0\fs24 , and all PREFIX, INC and LIB options are set for you.  Frameworks assume either a system framework, or the framework is in 
\f1\fs20 /Library/Frameworks
\f0\fs24 .\
\
For library forms, the PREFIX (described later) defaults to 
\f1\fs20 /usr/local
\f0\fs24 .  If this is where your libraries are installed, setting the form to 
\f1\fs20 shared
\f0\fs24  or 
\f1\fs20 static
\f0\fs24  is all that's needed.\
\
The version for GRASS and Python can't be detected by the config file, so make sure these are correct.\
\
See detailed dependency notes below.\
\
\
\ul Bundle options\ulnone  - 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 only logic 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.\
\
Some of the bundle targets don't exist yet, but can easily be created as needed.  Lazyness again.\
\
\
\ul Prefixes\ulnone  - If you have unix libraries installed in a location other than 
\f1\fs20 /usr/local
\f0\fs24 , the next section is where you can change those.  \ul Make sure to check these for any library forms\ulnone .\
\
\
\ul Notes for dependencies\ulnone \
\
- Postgres - An alternative to bundling Postgres is to build Qgis with a static libpq.  There are 
\f1\fs20 shared
\f0\fs24  and 
\f1\fs20 static
\f0\fs24  forms in the settings.\
\
- GRASS - GRASS.app \ul must\ulnone  be installed in /Applications directly, as it was built, not in a subfolder in /Applications or some other folder.  This goes for building Qgis as well as running it to use full GRASS support.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b \cf0 Build Targets
\b0 \
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \ul Full QGIS\ulnone   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 
\i will
\i0  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.\
\
\ul Cleaning\ulnone  - the clean the project, first set the \ul extra clean\ulnone  target as active and build it.  Then 
\b Clean All
\b0 .\
\
Or instead, trash the build and generated folders from the project folder (NOT from the project itself!).\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b \cf0 Build Products\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural

\b0 \cf0 \
When finished building, The final \ul Qgis.app\ulnone  is put in the 
\f1\fs20 mac/xcode/build/[SDKSYS/]Release
\f0\fs24  folder.\
\
\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural
\cf0 - William Kyngesburye\
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural
{\field{\*\fldinst{HYPERLINK "mailto:kyngchaos@kyngchaos.com"}}{\fldrslt \cf0 kyngchaos@kyngchaos.com}}
\fs20 \
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural
{\field{\*\fldinst{HYPERLINK "http://www.kyngchaos.com"}}{\fldrslt 
\fs24 \cf0 http://www.kyngchaos.com/}}
\fs24 \
}