SDKs

Xcode uses SDK bundles to gather the resources needed to build code against a desired target. SDK bundles are comprised of a plist file named SDKSettings.plist which dictates the settings used for that particular SDK and how it should be consumed by Xcode. There are two types of SDK bundles, Base and Sparse, which perform different functions. This post documents how to create your own SDK bundles that can be used with Xcode.

Table of Contents

• SDK Types
• Configuration
• SDK Contents
• Using with Xcode
• Related Radars

SDK Types

#####Base SDK These are the type of SDKs that ship with Xcode. They contain the all the headers and system libraries/frameworks necessary to build code against a specific OS version. Only one Base SDK can be used for a target for compilation. The Base SDK is assigned by specifying SDKROOT for the target.

#####Sparse SDK These are SDK bundles that contain supplimental libraries/frameworks and headers. Sparse SDKs have been supported for a long time in Xcode. While only one Base SDK can be used, multiple Sparse SDKs can be used in conjunction with the Base SDK to provide access to additional resources.

↑ Table of Contents

Configuration

#####SDKSettings.plist The SDKSettings.plist file is a plist that contains information necessary for loading and resolving the SDK within Xcode. This file lives at the root of the SDK bundle.

#####Custom Environments

Note: This only applies to Base SDKs, Sparse SDKs don't have these settings read from them.

The DefaultProperties and CustomProperties dictionary items on this plist can be used to enhance the build process. They are treated as SDK level build settings that all targets should inherit. For example, if you create a SDK that must always have -ObjC passed, you can add a key to DefaultProperities for OTHER_LDFLAGS with that flag as the value. This means you won't have to add that flag on the project or target level, it will already be inherited from the SDK. Similiarly you can use OTHER_CFLAGS to provide additional library and header search paths for your SDK.

If you need to specify supplimentary variables to use with part of your build process, eg relative paths to a framework or library, they can be provided in the CustomProperties dictionary. To create relative paths for any files in your SDK, use $(SDK_DIR) as the start of your path. This will provide the path to the root of the SDK bundle. Example of defining a path to a specific framework in the SDK:

...
<key>CustomProperties</key>
<dict>
    <key>MY_CUSTOM_FRAMEWORK_NAME</key>
    <string>Foo</string>
    <key>MY_CUSTOM_FRAMEWORK_PATH</key>
    <string>$(SDK_DIR)/System/Library/Frameworks/$(MY_CUSTOM_FRAMEWORK).framework</string>
</dict>
...

#####Example Base SDKSettings.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CanonicalName</key>
    <string>macosx10.9</string>
    <key>CustomProperties</key>
    <dict>
        <key>KERNEL_EXTENSION_HEADER_SEARCH_PATHS</key>
        <string>$(KERNEL_FRAMEWORK)/PrivateHeaders $(KERNEL_FRAMEWORK_HEADERS)</string>
    </dict>
    <key>DefaultProperties</key>
    <dict>
        <key>MACOSX_DEPLOYMENT_TARGET</key>
        <string>10.9</string>
        <key>PLATFORM_NAME</key>
        <string>macosx</string>
        <key>DEFAULT_KEXT_INSTALL_PATH</key>
        <string>$(LIBRARY_KEXT_INSTALL_PATH)</string>
    </dict>
    <key>DisplayName</key>
    <string>OS X 10.9</string>
    <key>MaximumDeploymentTarget</key>
    <string>10.9</string>
    <key>MinimalDisplayName</key>
    <string>10.9</string>
    <key>MinimumSupportedToolsVersion</key>
    <string>3.2</string>
    <key>SupportedBuildToolComponents</key>
    <array>
        <string>com.apple.compilers.gcc.headers.4_2</string>
    </array>
    <key>Version</key>
    <string>10.9</string>
    <key>isBaseSDK</key>
    <string>YES</string>
</dict>
</plist>

#####Example Sparse SDKSettings.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>AlternateSDK</key>
    <string>macosx10.9</string>
    <key>CanonicalName</key>
    <string>PrivateMacOSX10.9</string>
    <key>CustomProperties</key>
    <dict/>
    <key>DefaultProperties</key>
    <dict/>
    <key>DisplayName</key>
    <string>OS X Private (10.9)</string>
    <key>MaximumDeploymentTarget</key>
    <string>10.9</string>
    <key>MinimalDisplayName</key>
    <string>Private (10.9)</string>
    <key>MinimumSupportedToolsVersion</key>
    <string>3.2</string>
    <key>SupportedBuildToolComponents</key>
    <array>
        <string>com.apple.compilers.gcc.headers.4_2</string>
    </array>
    <key>Version</key>
    <string>Private (10.9)</string>
    <key>isBaseSDK</key>
    <string>NO</string>
</dict>
</plist>

↑ Table of Contents

SDK Contents

An SDK can contain anything necessary to perform a build. They typically contain frameworks, libraries, headers, resource, scripts/binaries, and any other type of asset that the build system would rely on.

####Frameworks, Libraries, and Headers Xcode will automatically search specific locations for any frameworks, libraries, and headers that have been included in the SDK bundle. These paths can differ based on the type of the SDK, additional paths can be specified by using the -isystem and -iframework flags to the compiler. Placing files in the locations listed below according to SDK type and if the files are a framework/library/headers to make them be automatically found. (All paths are based on the root of the SDK bundle)

####Assets Additional types of assets (graphics, fonts, bundles, strings files, etc) can be bundled as part of a SDK. There is no built-in support for finding any of these assets in the SDK. You will have to provide a way to access them from the SDK so they can be utilized.

####Executables While it is possible to ship scripts and executable binaries as part of an SDK bundle, Xcode's tooling doesn't know how to find these based on the specified SDK. To access these files you need to define the paths to run them directly since xcrun won't find them. If they are part of the Base SDK, then they can be found by using $(SDKROOT) as the base path or custom variables set via the SDKSettings.plist, however if they are part of a Sparse SDK then you will have to define the paths yourself.

↑ Table of Contents

Using with Xcode

#####Base SDK Xcode searches for Base SDKs based on the target platform bundles found in /Platforms/ directory in the currently selected DEVELOPER_DIR path. The search path for SDKs in a platform bundle is /Developer/SDKs/, eg:

|-- /Applications/Xcode.app/Contents/Developer/Platforms/
    |-- MacOSX.platform
        |-- Developer
            |-- SDKs
                | -- MacOSX10.9.sdk
                | -- MacOSX10.10.sdk
    |-- iPhoneOS.platform
        |-- Developer
            |-- SDKs
                | -- iPhoneOS.sdk
    |-- iPhoneSimulator.platform
        |-- Developer
            |-- SDKs
                | -- iPhoneSimulator.sdk

The xcodebuild command line tool allows you to specify the SDK to use when building by providing a flag and either a path or name of an SDK (see CanonicalName in SDKSettings.plist). This tool will find SDKs specified by path, if they exist inside of the current DEVELOPER_DIR path. If you specify a SDK by path that exist outside of that directory then it will be ignore and fall back to the default SDK. To view the names of SDKs that are found by xcodebuild and Xcode you can run the following command:

$ xcodebuild -showsdks
OS X SDKs:
    OS X 10.9                       -sdk macosx10.9
    OS X 10.10                      -sdk macosx10.10

iOS SDKs:
    iOS 8.2                         -sdk iphoneos8.2

iOS Simulator SDKs:
    Simulator - iOS 8.2             -sdk iphonesimulator8.2

#####Sparse SDK Sparse SDKs must be specified using the ADDITIONAL_SDKS build setting. Multiple Sparse SDKs can be specified, they must be paths to the SDK bundle directory and each path must be separated by a space. The list is sorted by precedence, SDKs higher in the list will be searched first. If a header or library exists in more than one SDK, the first instance that is found will be used. The build system Xcode uses will resolve what additional flags must be added to compile.

Linking:

Linking libraries and frameworks from a Sparse SDK becomes a bit more opaque than linking a library that resides in a Base SDK. When adding a library or framework to link from a target's Build Phases panel, Xcode will only display a list of libraries and frameworks that are in the Base SDK. You can use the "Add Other" button to navigate to the library you want to link, however this can lead to Xcode using absolute paths when adding the library as a reference to the project file. This will work fine until the Sparse SDK is moved or the path otherwise changes. To avoid this issue you can link the library by supplying the linker flags for it; either -l <library name> for stand alone libraries, or -framework <framework name> for frameworks. Since Xcode's build system will already be supplying the search paths for the Sparse SDK based on what includes you have, this will properly resolve and link.

Copying:

To handle copying resources or frameworks into an application bundle I would recommend either:

• setting up an xcconfig file that has relative paths to the Sparse SDK and has variables to the files that need to be copied so they can be accessed by a script to perform the copy into the application bundle before signing. Example xcconfig file:

    // Additional SDKs.xcconfig
  
    // defining variables for the first Sparse SDK that should be used
    FOO_SDK = ~/Library/Application\ Support/Developer/Shared/Xcode/SDKs/Foo.sparse.sdk
    TESTING_FRAMEWORK = Testing
    COPY_TESTINGFRAMEWORK_PATH = $(FOO_SDK)/System/Library/Frameworks/$(TESTING_FRAMEWORK).framework
  
    // defining variables for the second Sparse SDK that should be used
    BAR_SDK = ~/Library/Application\ Support/Developer/Shared/Xcode/SDKs/Bar.sparse.sdk
    UI_ADDITIONS_LIBRARY = UIAdditions
    UI_ADDITIONS_LIBRARY_PATH = $(BAR_SDK)/usr/lib/lib$(UI_ADDITIONS_LIBRARY).dylib
  
    // setting the ordering of the additional Sparse SDKs
    ADDITIONAL_SDKS = $(FOO_SDK) $(BAR_SDK)
  
    //  Configuring the linker flags to link the Testing framework from the first sparse SDK and
    // to link the UIAdditions library from the second Sparse SDK
    OTHER_LDFLAGS = $(inherited) -framework $(TESTING_FRAMEWORK) -l $(UI_ADDITIONS_LIBRARY)
  
    //   Now you have the variables $(COPY_TESTINGFRAMEWORK_PATH) and $(UI_ADDITIONS_LIBRARY_PATH) defined
    // and you can add an additional script phase after the regular Copy Items build phase that can copy 
    // these paths into the application bundle in the correct locations. You may also need to sign them 
    // after copying them manually like this depending on what your target requires.

  (Note: Please see my post about xcconfig files if you are unfamiliar with using xcconfig files)

• adding the Sparse SDK to the project file as a reference. This would allow you to link as part of the Link Libraries build phase, and not have to add linker flags for each library. Note that Xcode will add the reference as an absolute path by default, changing the path to be defined as a relative path to prevent it breaking can be difficult and may require editing the project.pbxproj file directly.

↑ Table of Contents

Related Radars

↑ Table of Contents

If this blog post was helpful to you, please consider donating to keep this blog alive, thank you!