---------------------------------------------------------------------------
Building ClanLib on Mac OS X
---------------------------------------------------------------------------

1. Getting Started
2. Building ClanLib
3. Running Example Applications
4. Creating Applications with ClanLib
5. Universal Binaries
6. F.A.Q.
7. Problems?

1. Getting Started
---------------------------------------------------------------------------
The ClanLib Xcode project file was created with Xcode 1.5, so download and
install that (or something newer) before continuing.

In order to build ClanLib, you need to locate a few dependencies.
The required frameworks depend upon which ClanLib modules you will build.
You will most likely require at least libjpeg and libpng as ClanDisplay
requires those frameworks and several other ClanLib components require
ClanDisplay. The available external frameworks are:

- libjpeg
- libpng
- mikmod
- Ogg
- SDL
- Vorbis

With the likely exception of libjpeg and libpng, the source code and Xcode
project files for each of these frameworks can be found at their respective
websites (use Google). To make things easier, all of them have been pre-built
and collected at these URLs for easy downloading:

- Mac OS X 10.4+ Universal (PowerPC + Intel):
- http://www.clanlib.org/download-binaries-osx-gcc40-universal.html

- Mac OS X 10.4+ PowerPC Only:
- http://www.clanlib.org/download-binaries-osx-gcc40.html

- Older Mac OS X PowerPC Only:
- http://www.clanlib.org/download-binaries-osx-gcc33.html

Once you have all of the external frameworks collected, place them into
a "Frameworks" folder in your "ClanLib-0.8" folder (the same folder that
the ClanLib.xcode project file is in) as this is where the ClanLib Xcode
project expects them to be. You will have to create this folder manually.
If you want them somewhere else, then you will have to point the way to
Xcode - in which case you are on your own.  :-)

2. Building ClanLib
---------------------------------------------------------------------------
Now that you've installed Xcode and got the other frameworks, go ahead and
open the ClanLib.xcode project file. (If you are using a newer version of
Xcode it will prompt to upgrade the project file - do it.) The project file
contains several targets which build each component of ClanLib as a
separate framework. These resulting frameworks are private frameworks which
are meant to be copied/embedded into the bundle for the application you are
creating. This means your finished application will be self-contained as
far as ClanLib is concerned and not require installation of any components
onto end-user machines.

Select the ClanLib target in the Xcode project and hit build. The resulting
frameworks are placed into a "MacOSX" folder within the same folder as the
ClanLib.xcode file itself resides. Inside this folder you will find all
required frameworks that are both part of ClanLib as well as the required
external frameworks. This should make it easy to see exactly what you will
need to bundle with your application.

If you don't need all of the modules (for instance, if you have no need for
ClanSDL and ClanMikMod), then simply edit the "ClanLib Distro" target and
delete the references to the targets you do not need. Don't forget to look
in the "Copy Files (MacOSX)" build phase as well!

3. Running Example Applications
---------------------------------------------------------------------------
The "Examples" folder has another Xcode project file named Examples.xcode.
This project has most (but not all) of the ClanLib example applications
pre-built as targets for easy testing. Simply set the active target to the
example you wish to try and hit build. The project file expects the ClanLib
frameworks to be in the "ClanLib-0.8/MacOSX/" folder which is where the
ClanLib.xcode project you used in step #2 places them.

4. Creating Applications with ClanLib
---------------------------------------------------------------------------
Now that you've got ClanLib and the modules you need built, it is time to
use them! Create an Xcode project however you like. (The Carbon Application
template is probably what you will want for now.) Then add the frameworks
you will need to your project - remember they are in the "MacOSX" folder as
mentioned in step 2 above. You will *always* need the ClanLib.framework as
well as any others you may have used (most certainly ClanCore.framework).

Don't forget to add the external frameworks that may be required by the
ClanLib components you are using! (These are libjpeg, libpng, etc. which
should have been copied into the "MacOSX" folder mentioned earlier and are
required by ClanDisplay.framework.) When adding external frameworks, Xcode
should automatically set your target to link with them. You can check to
make sure by opening the "Link Binary With Libraries" folder under your
target and verifying that they are represented there.  If not, simply drag
them into the folder.

The final preparation step is to add a "Copy Files" build phase to your
target. Set the location to "Frameworks" and then drag the various ClanLib
and required external frameworks (such as libjpeg and libpng) into the build
phase's folder.  This will cause Xcode to copy those frameworks directly into
your application's bundle and result in a self-contained binary which needs
no installer.  You do not need to copy in CoreServices, Carbon, libstdc++,
or any other frameworks or libraries that were automatically added by the
new project template (such as Carbon Application) when you created the new
project file with Xcode as they are always included with Mac OS X.

After your project file is prepared, add your source files and click build.
With luck it will all just work.

5. Universal Binaries
---------------------------------------------------------------------------
As you know, universial binaries will execute natively on PowerPC and Intel
based Macs using the same application bundle.  This means that you can
easily deploy Mac applications to users of both types of machines and be
sure that each user enjoys the performance they expect from their platform.

Building a universal version of your ClanLib application is easy and should
only require a few changes to your Xcode project file as well as ClanLib's
project file.  You must have Xcode 2.2 or newer in order for this to work
as well as universal versions of the required frameworks copied into your
"Frameworks" folder (as talked about above).  Additionally, it is important
that if you have previously built ClanLib *without* using the universal
frameworks, you must remove the non-universal frameworks from the "MacOSX"
folder that the ClanLib build process created (as was described above).
Sometimes Xcode doesn't notice that the new universal frameworks have
changed from the old and so they don't get replaced which can cause
problems if your project file refers to that "MacOSX" folder directly (as
is the case with the Examples Xcode project file provided in the ClanLib
"Examples" folder).

Since you should already have Xcode 2.2 or higher, you've likely already
opened and upgraded a copy of the ClanLib.xcode project file.  If not, do
so.  Be sure to tell Xcode to save the upgraded project file in the same
folder as the original ClanLib.xcode file (which it should do by default).

Once Xcode is open and the ClanLib project file is loaded, click on the
"Project" menu followed by the "Edit Project Settings" option.  The project
settings editor should pop up.  First switch to the "General" tab.  There
should be an option labled "Cross-Develop Using Target SDK" with a drop
down menu.  The menu likely reads something like "Current Mac OS."  Change
that to "Mac OS X 10.4 (Universal)."

Switch to the "Build" tab and look for the setting named "Architectures".
Select it and click "Edit" and check the boxes for both Intel and PowerPC
and click OK.

Now rebuild ClanLib.  It will take awhile since it'd building for two, now.

Once ClanLib has been built, simply make those same two changes to your own
project file and make sure it is refering to the now universal ClanLib and
supporting frameworks and rebuild your application.  Once the build is done
you will have a complete universal application bundle that will run on both
PowerPC and Intel based Macs with OS X 10.4 or later.  Of course to be safe
you should test the end product on both architectures before your final
deployment.


6. F.A.Q.

Q:

My try/catch doesn't seem to be able to catch CL_Error throws, instead I just get a segfault!

A:

Due to changes to default visibility attributes in gcc 4.0 it is necessary
to make the following changes to your XCode 2.2+ projects (ClanLib and your app's):

Look for "Symbols Hidden By Default" and set it to unchecked.  If it's
already unchecked, check it and uncheck it anyway, so it will override
whatever the default is.

That may be all that is needed, but perhaps you need Inline Functions Hidden
unchecked as well, not sure, something to try if you have any problems.

7. Problems?
---------------------------------------------------------------------------
Please read the FAQ on http://www.clanlib.org/ for common errors and
explanations.  There is also a Wiki at http://www.clanlib.org/wiki/.

If you cannot find the answer to your problem in the FAQ, feel free to ask
on the ClanLib user mailing list or join the #clanlib channel on IRC at
irc.freenode.net.

--
Enjoy,
The ClanLib development team

