An Objective-C/Perl Bridge

Navigating the Subversion repository on Sourceforge

Convenient installer packages are at the Downloads page on Sourceforge, but you may want to further customize the framework you ship with your app, or work with the latest bleeding edge still-in-development versions of the source code.

To begin with, you can check out a copy of the source from the Subversion repository at Sourceforge.net. Following those instructions, you'll find a "trunk" directory in your local copy. That's the main line of development, not an experimental tangent or other branch. In the "trunk" dir you'll find several subdirectories:

CamelBones/
Xcode project & code for the CamelBones framework, CPAN module, and libffi subprojects.
Examples/
Example projects that use CamelBones.
ExtLibs/
External libraries used for building PAR Kits.
IcebergProjects/
Create installer .mpkg files with Iceberg.
PerlSDKs/
Perl files from earlier Mac OS X releases. These Perls still run on Snow Leopard, thanks to binary compatibility, and they can build and test XS modules for older OS versions.
ShuX/
The CamelBones graphical pod reader.
WebSite/
You're looking at it. I use BBEdit to maintain it. Parts of pages are included from .inc files in (includes)/ subdirectory.
XcodeTemplates/
"New Project" and "New File" templates for different project types.

What you need

To build your own copy of CamelBones, you'll need at least the CamelBones/ subdirectory from Subversion. If you intend to also build your own custom PAR Kits, you may need the ExtLibs/ subdir as well. CamelBones builds on Snow Leopard, using Xcode 3.2; if you intend to deploy your build on older OS releases (Leopard and Tiger are both supported), you will also need either the PerlSDKs/ subdir, or the PerlSDKs installer package from SourceForge.net.

First, install the PerlSDKs - if you've downloaded them from Subversion, it's easiest to build and use an .mpkg installer. Go to IcebertProjects/ and open 'Perl SDKs.packproj' - you'll need Iceberg. In the PerlSDKs/ directory, each subdir has the Perl and OS version. Under that, there are Library/, System/, and usr/bin/ subdirectories that mirror the file trees that are installed at /.

What's in CamelBones.xcodeproj

Build Configurations

In CamelBones/, you'll find CamelBones.xcodeproj - that's where most of the fun stuff happens. It has four build configurations. All of the "Release" configurations create directory trees under "build/{$configname}", ready to be packaged for installation with Iceberg.

Debug
Builds CamelBones.framework in build/Debug/, builds CamelBones.pm with it and runs its "make test".
Release
Release is the "shared" configuration, with the framework configured to be installed in /Library/Frameworks, the CamelBones.pm module in /Library/Perl/, and PAR.pm & its prerequisites in /Developer/CamelBones/Perl/PAR.
Release-App-Embedded
This creates a framework that's configured to be embedded in a .app bundle. The CamelBones.pm, along with the PAR.pm module and its prerequisites, are installed in the Resources/ subdirectory within the framework. This framework is installed to /Developer/CamelBones/Frameworks/, and is meant to be embedded into an .app bundle's Frameworks/ subdirectory with a "Copy Files" build phase.
Release-Lib-Embedded
This framework is also configured to be embedded with a bundle, but not just the main application bundle. It uses a @loader_path install name instead of @application_path, so it can be used in a plugin bundle such as a preference pane or screen saver. This framework is installed to /Developer/CamelBones/Bundle-Frameworks/, and is meant to be embedded into a bundle's Frameworks/ subdirectory with a "Copy Files" build phase.

Targets

There are 17 targets. Actually, variations on five targets, and an All target.

CamelBones.framework
The framework. This provides the code to detect which support bundle to use and load it. Applications & bundles which link to this framework can run on any Perl for which a support bundle is included.
darwin-thread-multi-2level-*
Support bundles. Each of these is compiled and linked with the specified Perl, providing a version-specific implementation of the interface exposed by CamelBones.framework public API. These are built inside the Libraries/ subdirectory within the framework bundle.
Perl Module (x.y.z)
CamelBones.pm module for the specified Perl. This is just a "run script" build phase that uses the standard Makefile.PL incantation. For the "Debug" configuration, only the "make test" step is run. For "Release", the module is configured to be installed at "/Library/Perl" - like any CPAN module - and is staged separately under build/Release to be packaged by Iceberg. The "-App and -Lib-Embedded configs each install the module in the Resources/ subdirectory of the framework.
PAR Kits (x.y.z)
Builds the PAR kits using the specified Perl. Runs the build-*kit.pl scripts found in the CamelBones/PAR Kits group. For the "Debug" build configuration, all of the PAR Kit modules are downloaded, built, and tested, but not staged. For "Release", the PAR.pm module and its prerequisites are staged separately under build/Release, to be packaged by Iceberg. For -App- and -Lib-Embedded configurations, PAR.pm & its prerequisites are bundled into the Resources/ directory of the built framework. For all three Release-* configurations, the .par bundles in build/ are updated.
Snow Leopard, Leopard, Tiger, Panther
Builds the framework, support bundle, Perl module, and PAR Kits. For the support bundle, Perl module, and PAR Kits, builds only for a single OS version.
All
The whole enchilada. Currently builds only Snow Leopard, Leopard, and Tiger support.

Rolling your own

The most common reason to build your own custom CamelBones distribution is to save space - if your app uses newer APIs that are only available on Snow Leopard, then including support bundles and the PAR module for Leopard & Tiger is wasted space. To do that, simply modify the "All" target, deleting its dependencies on specific OS version targets you don't need to support.

Another common goal is to customize which CPAN modules are included in the PAR kits bundled with your app. These are built using the programmatic API to CPAN.pm. Each of the PAR Kits (x.y.z) targets has a "run script" build phase that runs the various build-*kit.pl scripts. You can add entirely new PAR bundles by cloning one of the build-*kit.pl scripts, then modifying the various "run script" build phases to include the new script. Or, you can edit one or more of the scripts to customize what modules are included. Or, if your app does not use PAR Kits at all, you can modify each of the OS version targets, removing its dependency on the associated PAR Kit (x.y.z) target.

Naturally, you can also do both - modify which (if any) modules built into the various .par bundles, and the OS versions for which the modules are built.