Exporting Your Framework Interface

When you build a framework or application using Xcode, the linker exports all of the symbols defined in your code by default. For a shipping framework with many symbols, this can lead to performance problems at runtime. When a framework is loaded, the dynamic link editor loads the symbols associated with the framework. If a framework contains a number of private functions, the symbols for those private functions are not going to be used but are still loaded along with symbols for the public functions. Loading these extra symbols not only wastes memory, it also requires more work to walk the list during a symbol lookup.

In Xcode, you can limit the symbols exported by your executable by specifying an exports file in your linker options.

Creating Your Exports File

An exports file is a simple text file (.txt or other text file extension) that contains the list of symbols you want to export. To create the file, add a new empty file to your Xcode project. To this file, add the list of symbols you want to export, one symbol per line.

For ANSI C-based code, you can usually just prefix an underscore character to the name of a function or variable to get the symbol name. For languages like C++, which uses mangled symbol names, you may need to run the nm tool to get the list of existing symbol names. Run nm with the -g option to see the currently exported symbols. You can then copy the output from the tool and paste it into your exports file, removing any extraneous information. The following text shows some sample output for a Cocoa framework generated by nm:

 U .objc_class_name_NSDate
b000ad54 T _InitCocoaFW
b000aea8 T _addNumbers
b000ade8 T _getInitDate
         U _objc_msgSend

To export the framework functions specified in this output, you would create a text file with this text:

_InitCocoaFW
_addNumbers
_getInitDate

You can temporarily remove a symbol from your exports file by putting a pound sign at the beginning of the line containing the symbol. For example, the following text temporarily removes the _getInitDate function from the exports list:

_InitCocoaFW
_addNumbers
#_getInitDate

Specifying Your Exports File

To specify an exports file for your framework in Xcode, do the following:

  1. Open your project in Xcode.

  2. Add your exports file to the project, and place it in the Resources group.

  3. Open the framework target’s Info window and click Build.

  4. Set the Exported Symbols File build setting to the name of your exports file.

    You can locate this build setting by choosing All from the Collections pop-up menu and entering its name in the search field.

If you want to export all symbols except for a restricted subset, you can use the Unexported Symbol Files build setting to do so. Create your symbols file as before, but this time include the list of symbols you do not want to export. In the Linking build settings for the target, find the Unexported Symbol Files setting and set its value to the name of your file.

If the Unexported Symbol Files build setting is not present, as it might not be on versions of Xcode prior to v2.2, you can use the “Other linker flags” build setting instead. To hide a set of symbols, set the value of that build setting to the following text, replacing exports_filename with the name of your exports file:

-unexported_symbols_listexports_filename