Using Static iOS Libraries

This is part 1 of a 2 part series on using and creating static iOS libraries. See part two: Creating static iOS Libraries. for info on how to create your own static libraries for distribution.

All of the below steps can be applied generally to include any static library in your current iOS project.

General Procedure

  • Fork & checkout the static library into a sub folder of your project. (I like to create a “Third Party” folder & Xcode group.)
mkdir -p ~/Desktop/StaticLibraryDemo/"Third Party"
cd ~/Desktop/StaticLibraryDemo/"Third Party"
git clone git://
  • Drag the static libraries Xcode project into your applications Xcode project.
  • Select your applications current target.
  • Select “Build Phases”.
  • Add <StaticLibName> to your targets “Target Dependencies” section.
  • Add lib<staticLibName>.a to the “Link Binary With Libraries” section.
  • Link any other dependant frameworks. (e.g. Addressbook.framework or CoreLocation.framework)
  • Select “Build Settings”.
  • Find Header Search Paths and add an entry consisting of include/. (The library may be set up to use another path. If this is the case, see the “Trouble Finding Headers” section below.) (I usually select the recursive option.)
  • Make sure -all_load -ObjC is added to the Other Linker Flags section. (This makes sure everything in the static library is linked, even if not used at compile time. i.e. making it available at run time.)
  • Finally include the static library headers in your source files using #import <RHAddressBook/AddressBook.h>.

Handy Tips

Trouble Finding Headers

If you are having trouble finding headers in your project even though you have added include/ to your Header Search Paths you may be running into an issue whereby the static library is being built with one configuration name and your project is building with another. (i.e. Debug vs DebugStaging)

Xcode will, on finding a matching configuration name in a sub-project use that configuration to build the sub-projects targets, however if it can’t find a matching configuration it uses the projects default config. This can lead to problems finding the matching headers.

Some static libs work around this by setting their public / private headers folder paths to be ../../Headers/$(TARGET_NAME), i.e. in the folder above the config specific folder that Xcode creates when building projects. If this is the case you will need to add this path to your header search paths instead of include/.

Another way to work around this is to use the direct path to the .h files inside your Third Party folder, i.e. set Header Search Paths to ""$(PROJECT_DIR)/Third Party" making sure to select recursive.

Finally, my preferred way depending on the project is to actually modify the static libraries project (You did fork the framework, didn’t you?), adding extra configurations that match the parent projects configuration names.

Headers being included in Xcode archives

If the path the static library is putting its headers into starts with a slash i.e. /include/$(TARGET_NAME), Xcode will include the headers in archived builds (because it’s a fully rooted path). This leads to app store validation failing when trying to upload a build. The solution to this problem is to change the public headers folder path in the static lib to no longer include the /.

Ideally you would set Public Headers Folder Path to include/$(TARGET_NAME) and Private Headers Folder Path to $(PUBLIC_HEADERS_FOLDER_PATH)/Private.

Specific Build Settings

Your Project

HEADER_SEARCH_PATHS="include/**"; /*Header Search Paths (the ** indicates recursive)*/

Static Library Project

PUBLIC_HEADERS_FOLDER_PATH="include/$(TARGET_NAME)"; /*Public Headers Folder Path*/
Tagged ,

2 thoughts on “Using Static iOS Libraries

  1. […] is part 2 of a 2 part series on using and creating static iOS libraries. See part one: Using static iOS Libraries. for info on how to use static libraries in your own […]

  2. Morten Hjortshøj NIelsen says:

    Hi Richard.

    thank you for making RHAddressBook, im looking at it right now and are playing around with it. It seems to have spared me tons of time IF NOT…. 😉 there is no gender on RHPerson, for a moment i thought that “kind” was man woman, but i was sad to find out that is was person/organization. I am hoping and preying that you sometime in the near future will add gender to this class, so i do not have to learn C myself.

    I do not know if gender is new to the address book, but its there on the iphone ios6 contacts. Again i really hope you will add this parameter, and again thank you very much for taking the time to do RHAddressBook its an awesome library.

    Best Regards
    Morten from Denmark

Leave a Reply

Your email address will not be published. Required fields are marked *