Monday, August 02, 2010

ClanLib 2.2 on Mac OSX 10.6

These are just some notes on building the new version of ClanLib, 2.2, on Snow Leopard. The XCode version of ClanLib using frameworks is pretty broken and hasn't been maintained in some time. It also doesn't look the developers will fix this any time soon. To quote some of the issues:

[...] The 0.9 code base is partly based on 0.8 which already had Mac support, so most of the module are trivial to fix into compiling again. The main porting issue is clanDisplay+clanGL where the window management and AGL context management code needs to be updated. Most of that can once again be taken from 0.8 and updated from that point forward (the code might even already be in 0.9 in a broken state - haven't checked), but you might also just find it easier to rewrite parts of that platform specific code.
In general the code in ClanLib is very modular in the sense that the Win32, X11 and OSX code is usually cleanly separated so porting is mostly just a matter of finding the equivalent OS X functions. Unfortunately when I originally did the OS X port, I mainly relied on the Carbon API mixed with some posix stuff (pthreads mainly) and I hear Apple removed support for Carbon in 64 bit OS X. Having virtually no experience with Objective C or Cocoa I do not know how difficult it is to switch to the equivalent Cocoa functions.
One last issue regarding OS X support is that I personally rely on a simple program called scan.cpp that reside in the Setup/OSX directory which generates a makefile for my purposes. The reason I bring this up is because that while there exist a XCode project, it is currently out of date. It is probably just a matter of bringing the source files into sync to get that project back and operational, but I am personally so allergic to the IDE of XCode that I reverted back to my makefile generator when I ported clanCore and clanNetwork to Mac in 0.9. You are naturally free to fix this project (which officially is the way we tell users to build 0.8 for Mac), but I will have to stay on the makefile myself simply because Apple changed the XCode project file format and my ancient G4 Powerbook with OS X 10.3.9 on it cannot read it after you update it. [source]
I forgot to mention that we will naturally gladly update the framework bundles for any dependency library used by ClanLib. The only problem is that I somewhat forgot how we built them and at least at the time the documentation on library framework bundles provided by Apple was somewhat limited.
Since I do not know how much experience you have with building framework bundles I'll just tell you what I know and hopefully you can use that for something. 
Technically a library framework bundle is simply a normal dynamic library arranged in a certain directory structure (just like application bundles are just directories). In traditional unix environments (BSD, linux, etc.) the include files are placed in /usr/include/ClanLib-0.9 and the dynamic libraries in /usr/lib. But for a framework library those same files are placed in ~/Library/Frameworks/LibraryName/Headers and ~/Library/Frameworks/LibraryName/LibraryName.
To port any library to an OS X library bundle is therefore a "simple" task of simply taking the header files and the output dynamic library and place them in this directory structure. Unfortunately it seems the linker in OS X is rather dumb (at least in 10.3) and requires the dynamic library file to built directly into this directory structure. If you want more details on how to do this manually outside XCode, try take a look at the scan.cpp program that came with ClanLib.
An easier option may be to simply recreate the makefile for the dependency library in XCode. Using this strategy will ensure that the framework bundle is at least correctly built, but great care must be taken to ensure that it is the same source files and defines that are used for the build. I think the current framework bundles available on the website were built using this strategy.
Finally we might be lucky that someone else already did create an OS X framework bundle for some of our dependency libraries. Googling for that first wouldn't hurt. [same source as above]

There are a few compilation errors with ClanLib 2.2 out of the box for Mac since it hasn't been maintained in a while. Anything inside #ifdef __APPLE__ is a little stale. Also, as stated, there is no support for certain features, like joystick input.

XCode Project

To fix the Mac issues, the easiest way (for me anyway) is to fix the XCode project. Source code is checked into the Gameres project. Also, on the Mac it seems that OpenGL is only supported via a framework, and I'd like to use OpenGL.

Dependencies are as follows. Apologies if I make any mistakes, these are vague notes from my install. We need to make everything 32-bit as ClanLib is 32-bit (like Allegro). So when you compile the following libraries do:
  • ./configure CFLAGS="-arch i386"
  • make
  • sudo make install
  • make clean
Libraries required by ClanLib. You can get these from the download page (in case you need binaries of the same versions).
  • libxml2: This is the XML library used by fontconfig. You'll have make this from source as the precompiled Mac binaries install as a framework.
  • fontconfig: I installed version 2.8.0. This required libxml2.
  • freetype2: I got version 2.4.1 of this font library.
  • libpng: I have version 1.4.3 of the PNG library. There seem to be some serious bugs with earlier versions so make sure you have 1.4.3 or later.
  • libjpeg: I got JPEG library version 8b (of 16-May-2010).
  • pcre: Regular expression library version 8.10.
Now, if installed at the default location, you should have some includes and libraries in /usr/local. I may add the binaries to Gameres at some point.

After a few hours work I managed to fix up the project and get it compiling and linking. It is currently untested and no doubt missing features.