This document provides instructions for encapsulating dynamic libraries (dylibs) within a framework in Xcode and ensuring the framework and any applications using the framework can locate the embedded dylibs. Key steps include copying dylibs into the framework, using install_name_tool to change library search paths, adding run scripts to apply changes on build, and configuring framework and application build settings to locate embedded libraries.

1. Dynamic Library Encapsulation
Written By: Cole Herzog
Last Updated: 5-Aug-2014
Version: 1.0
Encapsulating Libraries in Frameworks
Overview
This document was created to explain the process behind embedding a Dynamic-Linked Library
(Dylibs) inside of a Framework and is specific to Xcode development. Some of the information is
not specific on Xcode. A framework may be dependent on external DLLs, and as such must be
aware of their location on the host system. This document is targeted at frameworks that are
meant for use on multiple host systems.
Dylibs on Disk
The dylibs must be present on disk originally, but once they are copied into the Xcode
framework project they can be removed assuming everything was done correctly.
The dylibs can be installed through whichever means is most convenient. Brew is highly
recommended, though entirely optional. Once the dylibs are installed, locate them on disk and
retain the location.
Embedding Dylibs into the Framework
The majority of the work will be done in Xcode's Target Configuration and build settings
Windows.
With the Framework as the target:
1. Click on Build Phases
2. In the Top left area of the build phases tab hit the + button
Add a New Copy Files Phase
3. Drag and drop the dylibs into the newly created phase, or use the + button within the
phase and navigate to the dylibs
The Destination and Subpath options dictate the location of the library
Wrapper is the recommended destination
../$(VERSIONS_FOLDER_PATH)/$(FRAMEWORK_VERSION)/Library is the
recommended Subpath.
These are environment variables supplied by Xcode and can be found here
This will create a Folder called Library in

2. yourFrame.framework/Versions/Current
Current is a symlink likely pointing to A depending on the
framework
Note: You may place the dylibs wherever you would like inside of the framework, as long
as you can locate them using the Xcode environment variables. These variables allow the
framework to locate the libraries no matter what the current host system's file heirarchy
is.
Helping the Framework locate the Dylibs
While the Dylibs have now been added to the framework's file heirarchy, the unix executable
portion of the framework will not bother looking there unless explicitly told to. Achieving this
requires an understand of @rpath , @executable_path , possibly @loader_path , otool,
install_name_tool, and writing scripts.
@executable_path
executable_path is the most basic of the three paths. This is simply the location of the folder
MacOS within the calling application.
Example: yourApp.app/Contents/MacOS
@loader_path
loader_path is very close to executable_path, and in the overwhelming majority of cases points
to the exact same folder. The difference is @loader_path will point to the location of whatever
loaded the framework. This is useful in the case of an application requiring a framework, and
then said framework requiring another framework. The app's embedded framework would
reference its embedded framework through @loader_path, as @executable_path will always
point to the Application itself.
Note: This was added in 10.4
@rpath
rpath is the most recently added, and most useful of the three path variables. rpath can be
described as a localized PATH variable. In Xcode the contents of @rpath can be found under the
Build Settings for the framework Target and is called Runpath Search Paths .
Example: If /tmp/ , /Libraries/Frameworks , and /etc/ were added to @rpath the
@rpath/myDir would expand into /tmp/myDir , /Libraries/Frameworks/myDir , and
/etc/myDir .
Note: This was added in 10.5

3. otool -L
Running the command otool -L on a unix executable will list all of the dependent libraries for
the executable as well as where the executable has been instructed to search for them. Altering
this list is how a framework can be told to search itself for its dependent libraries.
Example: otool -L
/Library/Frameworks/iTunesLibrary.framework/Versions/A/iTunesLibrary
install_name_tool
This command line tool is used to modify the list that otool -L gives. The syntax for changing
one of the entries is
install_name_tool -change old new target
Old refers to the path currently listed for the executable.
New refers to the path that will replace the listed Old path.
Target refers to the executable being changed.
Example: install_name_tool -change /usr/local/lib/libssh2.1.dylib
@rpath/$VERSIONS_FOLDER_PATH/$FRAMEWORK_VERSION/Library/libssh2.1.dylib
$BUILT_PRODUCTS_DIR/$VERSIONS_FOLDER_PATH/$FRAMEWORK_VERSION/$PROJECT
Note: The dylibs a framework lists as dependencies may also have dependencies.
install_name_tool must be used on these dylibs as well to explicitly tell them where to
search for the other dylibs they themselves are dependent on.
Scripts
Unfortunately, even though an executable has been delicately changed using install_name_tool,
every time the folder is cleaned and the framework is built a new executable will be created
without the necessary changes. To fix this Xcode can be told to run a script after building.
In the Top left area of the build phases tab hit the + button
Add a New Run Script Phase [This should be the final build phase]
In the text field type or copy + paste the script [The code, not the file]
All required install_name_tool scripts should be here, as shown in the
above example. As every situation is different this script must be created
specifically for each framework. @rpath should likely be the beginning of
the New argument for install_name_tool, and a path to the framework's
executable should be created using Xcode's environment variables for the
Target argument.

4. Note: The framework's dependent libraries must also have their dependencies changed in
this script as referenced in the note above.
Helping the Dylibs locate their Dylibs
As the most recent notes have mentioned, dylibs the framework is dependent on may have
dependencies themselves (sub dependencies). These sub dependencies must be included in
the project, and their dylibs must be altered using install_name_tool (likely with the help of otool
-L). These install_name_tool commands should be added to the framework's script.
Build Settings
Under the build settings tab for the framework the Skip Install option should be set to Yes .
The framework is not being installed anywhere, as it will be embedded itself within the calling
application. All required linker flags under the Other Linker Flags option must be set for any
added dylibs (check specific dylib’s documentation for more information).
Example: -lssh2
Embedding Frameworks into applications
While the work on the individual framework has been completed, the framework now has to be
encapsulated within the application, and the application has to be told where to look for its
frameworks.
1. Go to the application's Build Phases tab
2. In the Top left area of the build phases tab hit the + button
Add a New Copy Files Phase
Change the Destination to Frameworks
Copy only when installing should be unchecked
Either add of drag and drop the framework into the build phase
Note: This automatically copies the framework into
@executable_path/../Frameworks@executable_path/../Frameworks
Helping the application locate the frameworks
The framework has been added to the application in the correct location, but the application has
not been instructed to search for said framework.
1. Go to the application's Build Settings tab
2. The Runpath Search Paths setting (@rpath) needs to include
@executable_path/../Frameworks
If this is a framework calling another framework,

5. @loader_path/../Frameworks should be used instead
3. The Frameworks Search Paths setting needs to include
$(TARGET_BUILD_DIR)/$(FRAMEWORKS_FOLDER_PATH)
These bash variables point to the yourApp.app/Contents/Frameworks
directory
Finishing
The product should now have:
1. embedded dylibs in the framework
2. dylibs that know the location of their individual dependencies
3. a Framework that knows where to look for its dependent libraries
4. an Application with an embedded framework
5. an Application that knows where to find its dependent frameworks
Note: The application should now be a completely standalone application. If it is not, a
mistake was made. The best way to test this is to either delete or alter the names of all
required dylibs and frameworks on disk.