Mac OS X 10.5 Leopard Notes

Broken Binary Compatibility:

Apple has broken binary compatibility in a limited way between 10.4 and 10.5 when using OpenGL and C++. Under 32-bit, the GLenum type was changed from long (in 10.4 and before) to int (in 10.5).

Under 32-bit, sizeof(long) == sizeof(int) == 4-bytes. (In 64-bit, sizeof(long) == 8-bytes, sizeof(int) == 4-bytes) So in C 32-bit, binary compatibility is preserved.

But under C++, even though both types are 4-bytes under 32-bits, C++ name mangling rules treat int and long as fundamentally different types. Thus binary compatibility is broken if you try linking two pieces of code that use different types for GLenum.

This means: 1) If you have a 10.4 SDK (or before) built OSG framework, you cannot build an application using the 10.5 SDK or you will get strange undefined symbol errors if GLenum is used. This means don't develop against the 10.5 SDK on Leopard.

2) You cannot use a 10.5 SDK built OSG framework to build an application using the 10.4 SDK, otherwise this will also give you undefined symbol errors. This means don't develop with 10.5 built OSG frameworks when using the 10.4u SDK on Leopard or developing on 10.4 itself.

3) If you have a 10.4 SDK built OSG framework and a 10.4 SDK built application that uses it, this does *not* present a binary compatibility problem and you may be able to run on 10.5 (ignoring any different compatibility issues).

4) Similarly to #3, if you have a 10.5 SDK built framework and a 10.5 SDK built application that uses it, this does *not* present a binary compatibility problem and you may be able to run on 10.4 presuming there are no specific 10.5 dependencies. (But it is safer to build against the 10.4 SDK if you plan on deploying to 10.4 and use no 10.5 specific features.)

Basically, this means you can't intermix 10.4 and 10.5 frameworks.

You can slip around this problem if you manage to avoid the use of any code that uses GLenum. And pure C is not affected.

(Images demonstrate how to switch to building for 10.5.)

Show the user how to set the 10.5 SDK

Set the Mac OS X Deployment Target to 10.5

OSG 10.4 and 10.5 Cross-Compile SDK:

Xcode 3.0 introduces formal support for SDKs created by 3rd parties (like us). Since we now have binary incompatible frameworks, developing binaries for both 10.4 and 10.5 on the same system is a pain. Having a separate OSG 10.4 and 10.5 SDK may help minimize that pain.

Our SDK package may be found at:

Documentation is included with the package, but should be copied into the Wiki at some point.

X11 Link problems:

Another common problem developers might experience is:

ld: cycle in dylib re-exports with /usr/X11R6/lib/libGL.dylib
collect2: ld returned 1 exit status

Apple has a posted a Technical Q&A (QA1567) on this entitled "Compiling X11 / OpenGL applications on Mac OS X v.10.5 Leopard"

Some people have reported a problem similar to this and/or used the solution posted in this Q&A to resolve a problem building the osgdb_freetype plugin. However, I believe this is the wrong solution to this specific problem. In the osgdb_freetype case, the problem was one of three things: 1) The wrong libfreetype.dylib was being used (wrong SDK) 2) The libfreetype.dylib was not found (wrong path) 3) Extra/unneeded dependencies increasing the chance of triggering the cycle bug

For #1, the Xcode project was linking to /usr/X11R6/lib, but we should have been linking to $(SDKROOT)/usr/X11R6/lib. You would normally experience this problem when compiling against the 10.4u SDK on 10.5.

For #2, the problem was usually experienced by people building against the 10.5 SDK (on 10.5). The problem here is that Leopard has moved from to and the path is now /usr/X11/lib instead of X11R6. Within the SDK, there is no X11R6 path, so the library was not found.

The solution is quite simple. Change the link path line to:

-L$(SDKROOT)/usr/X11/lib -L$(SDKROOT)/usr/X11R6/lib

in the Other Linker Flags for the osgdb_freetype plugin. Remember to do this for all the build configurations you are using.

This is now fixed in the Xcode project in Subversion.

(Images show how to setup the correct settings yourself.)

osgdb_freetype Linker Options Setting

Correct linker options for osgdb_freetype

For #3, at one point in SVN, it turns out there were extra libraries being linked in which did manage to trigger this bug. However, removing those libraries made the cycle errors disappear so we were able to side-step this 'fix'.

If it turns out you do need the fix, be cautious to what you link to. Some people have been taking the Q&A example solution as a copy & paste solution. Notice that if you are building against an SDK such as the 10.4u SDK, the example will have you link to the native 10.5 OpenGL on your system instead of 10.4. We already know to have at least one binary compatibility issue already.

So you may want to make use of the $(SDKROOT) variable:

-dylib_file \


The CMake/OSG build system is still not quite ready for prime time. CMake has some general Leopard issues and the OS X/CMake community is trying to work through SDK support issues as the SDKs have become a more prominent part of building on OS X correctly. Framework support is still lacking in the CMake/OSG build system, though CMake CVS is gradually adding/fixing this feature to its code base.


OSG for OS X 64-bit is not ready. There are two major obstacles: 1) osgViewer 2) osgdb_qt

The osgViewer backend is written in Carbon and as far as I know, uses some deprecated APIs that are not available in 64-bit. I do not know if this can be easily cleaned up or not. However, I still believe the better long term solution is for a Cocoa based osgViewer backend to be written. However, nothing yet has been written for this as far as I know.

The example, osgviewerCocoa is close to if not already 64-bit clean. However, because the example uses osgViewer::GraphicsWindowEmbedded? which needlessly pulls in all the osgViewer Carbon backend dependencies, you will be unable to actually build osgviewerCocoa as 64-bit. But if you are in a hurry to get 64-bit on OS X, this might be where you want to start. Either strip away the Carbon dependencies from osgViewer, or take osgviewerCocoa and transform it into a Cocoa backend for osgViewer.

osgdb_qt is a QuickTime? based plugin that handles all image handling and movie handling on OS X. However, it is based on the old QuickTime? API which has been marked deprecated and will not survive the 64-bit transition. Thus this plugin needs to be replaced.

I have already submitted a new plugin called osgdb_ImageIO to osgSubmissions which attempts to assume all the image handling duties. This plugin is based on Apple's ImageIO framework which is the new low-level entry point to deal with all image types handled by the platform. Thus this plugin should handle a lot more image formats than the old QuickTime? plugin (e.g. JPEG2000, RAW, etc) and will get more as Apple adds support their system. ImageIO is available on 10.4 and 10.5.

However, the osgdb_ImageIO plugin does not handle movies unlike the old QuickTime? plugin. The current plan is to introduce a second plugin (osgdb_QTKit), which is based on the new QuickTime? Kit framework (10.4 and 10.5). This plugin will replace the movie handling capabilities of the old QuickTime? plugin.

Once both new plugins are in place and osgViewer is sorted out, we should be able to build a 32-bit/64-bit Universal Binary of OSG for OS X.

Mac OS X 10.3 and earlier users and QuickTime? for Windows users will still need to use the old QuickTime? plugin.

Xcode Project Templates:

Xcode 3.0 has moved things around. The old location was:

/Library/Application Support/Apple/Developer Tools/Project Templates/Application

The new scheme is:

/Library/Application Support/Developer/{3.0,Shared}/Xcode/Project Templates/Application

Specifying 3.0 will restrict them to only be available in Xcode 3.0, specifying Shared will make them available to 2.5, 3.0 and beyond.

I believe our templates will work in both, so Shared is a good location:

/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application

Also note you may place it in per-user locations, e.g.

~/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application

Xcode Documentation Browser Integration:

Xcode 3 introduces a formal/official way to integrate 3rd party documentation so it works seamlessly within the Xcode Documentation Browser. While we have not yet done any direct work to do this ourselves (a how-to write up would be most welcome), Doxygen has already taken the initiative to integrate this support. As OSG uses Doxygen already, we expect to be able to take advantage of this feature. Initial support is available in Doxygen's SVN. See the Doxygen mailing list (search for DOCSET) for more information.

Additional References

See Objective-C/C++ for basic information on Objective-C and Objective-C++.

See Mac OS X Tips and Tricks for more information/videos on getting started with Mac OS X and Xcode.