Library of components and shared code for applications targetted toward the iPhone OS.
C Objective-C C++ Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.images Being picky now. Jul 13, 2011
External Remove the submodules, just too annoying with them being all optional. Oct 14, 2014
Pearl-Cocoa Update printSuperHierarchy and create similar NSView category methods. Dec 29, 2014
Pearl-Crypto Fix usage of errstr. Aug 11, 2017
Pearl-Media instancetype usage + iOS 6 deprecation. Jan 31, 2013
Pearl-WS Use fullDescription for all error logging. Sep 22, 2014
Pearl.xcodeproj Remove PearlLayout. Aug 28, 2017
Pearl Fix support for void methods, more strict checking, support for CG st… Nov 19, 2017
PearlOSXTests Remove scrypt. Apr 9, 2017
PearlTests 64-bit iOS. Sep 21, 2013
PearliOSTests Remove scrypt. Apr 9, 2017
Raw/Pearl-Cocos2D Renamed iLibs -> Pearl + serious internal restructuring to make it mo… Jun 23, 2011
.gitmodules Revert "CrashKit support." Dec 2, 2011
.travis.yml Prepare for Travis-CI. Jan 26, 2014
LICENSE Re-license under Apache for App Store compatibility. Sep 11, 2013
Pearl-Bridging-Header.h Support for Swift. Nov 22, 2015
Pearl-Prefix.pch Tweaks to Pearl-Prefix. Oct 21, 2015
PearlTests-Prefix.pch Remove scrypt. Apr 9, 2017
README.markdown Remove the submodules, just too annoying with them being all optional. Oct 14, 2014


Gittip Travis CI

Getting Started

Pearl is a modularized iOS library that provides convenience utilities for a wide range of fields.

You can use only the modules that you require. Some modules do depend on others, and some have external dependencies. You'll need to add these dependant modules and externals to your project as well.

Any external dependencies can be checked out from the URL in the External/[project]/.source file.


The standard way of adding Pearl to your project is by following these steps:

  1. Add the Pearl code to your project. If your project is in a GIT repository, this will do, from your project root:

    mkdir -p External && git submodule add git:// External/Pearl

  2. Create a Pearl static library target in your project.

  3. Navigate to the Build Phases settings of your main target and add the newly created Pearl target as a Target Dependency, and its static library under Link Binary With Libraries.

  4. In your Project Navigator, choose where you want to place the code of the Pearl modules and add the directory of each Pearl module you wish to use to your new Pearl target.

  5. (optional) If any of the Pearl modules you've selected for use depend on other Pearl modules or external dependencies, add those modules and dependencies to your project as well. I recommend you make separate targets for each external dependency, but that's really up to you.

  6. Open the Pearl-Prefix.pch that was created for your Pearl target in step 1, and add configuration reflecting your choice of Pearl modules (see below).

  7. Open the prefix file of your main target and import Pearl's prefix:

    #import "Pearl-Prefix.pch"

Adding a new target Configuring build phases Adding module and dependency sources Configuring your Pearl prefix Configuring your application prefix

Pearl Configuration

Pearl modules can use each other when they know other Pearl modules are available. For instance, when the Pearl-Media module is activated, the Pearl-Cocos2D module will activate its sound effect and music support. In order for modules to know which other modules are enabled, you need to define which modules you've selected for inclusion in your project. You do this in your Pearl target's prefix, which will probably be Pearl-Prefix.pch, by enumerating each module with #define statements. For example, assuming you selected Pearl, Pearl-Media and Pearl-Cocos2D, you'd specify these #define statements in your Pearl prefix:

#define PEARL

After having defined which modules you'll be using, you need to import their module headers. Pearl module headers are a single header file for each module that immediately imports all the headers of each file provided by that module. Importing the module header of each Pearl module you'll be using gives you instant access to any of those Pearl modules' features. Assuming the example above, you'd import the following:

#import "Pearl.h"
#import "Pearl-Media.h"
#import "Pearl-Cocos2D.h"

Note that Pearl module headers are set up to break the build if you try to import them without first having set up your defines correctly. This is a protection measure to make sure you don't forget to set up your defines as specified above.

With your Pearl-Prefix.pch file set up, your Pearl target should now build fine. What's left is to give your main application's target access to Pearl. You'd effectively have to do the same thing, but it's simpler (and safer) to just import your Pearl prefix in your main application's prefix. For instance, in the Gorillas application, I have a Gorillas-Prefix.pch which contains:

#import "Pearl-Prefix.pch"

If you're writing an open source library that uses Pearl, it's best for your library's prefix file to also assert that the Pearl-Prefix.pch of the library's host project has correctly imported the Pearl modules necessary for the library, when it builds your library's code. I recommend you do that by putting the following in your library's prefix, instead of the one-liner above:

#import "Pearl-Prefix.pch"
#if !defined(PEARL) || !defined(PEARL_CRYPTO)
    #error Pearl-Prefix.pch should define: PEARL PEARL_CRYPTO

In this example, the library requires the Pearl and Pearl-Crypto modules. If your library's prefix declares this, it forces the host application to have a Pearl-Prefix.pch that correctly defines and imports these modules. If you don't do this and the host application's Pearl-Prefix.pch omits certain Pearl modules that you need, linkage errors or runtime errors may follow as Pearl won't be compiled with the correct modules.