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.
- 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://github.com/heardrwt/RHAddressBook.git
- Drag the static libraries Xcode project into your applications Xcode project.
- Select your applications current target.
- Select “Build Phases”.
<StaticLibName>to your targets “Target Dependencies” section.
lib<staticLibName>.ato the “Link Binary With Libraries” section.
- Link any other dependant frameworks. (e.g. Addressbook.framework or CoreLocation.framework)
- Select “Build Settings”.
Header Search Pathsand 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 -ObjCis added to the
Other Linker Flagssection. (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
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
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
Private Headers Folder Path to
Specific Build Settings
HEADER_SEARCH_PATHS="include/**"; /*Header Search Paths (the ** indicates recursive)*/
Static Library Project
PUBLIC_HEADERS_FOLDER_PATH="include/$(TARGET_NAME)"; /*Public Headers Folder Path*/ PRIVATE_HEADERS_FOLDER_PATH="$(PUBLIC_HEADERS_FOLDER_PATH)/Private"; /*Private Headers Folder Path*/