Configuring a Project for SDK-Based Development

This chapter describes the configuration of installed SDKs and explains how to set up your Xcode project to use an SDK.

SDK Header Files and Stub Libraries

When you install the SDKs, the installer creates a /Developer/SDKs directory. This directory contains several subdirectories, each of which provides the complete set of header files and stub libraries that shipped for a particular version of Mac OS X. The Mac OS X SDKs are named by major version, such as 10.4 and 10.5, but they include the latest minor version as well.

Using SDKs allows you to use new APIs introduced in a system update. When new functionality is added as part of a system update, the system update itself does not typically contain updated header files reflecting the change. The SDKs, however, do contain updated header files.

Each SDK resembles the directory hierarchy of the operating system release it represents: it has usr, System, Library, and Developer directories at its top level. Each of these directories is in turn populated with directories containing the headers and libraries that would be present in that version of the operating system with Xcode Developer Tools installed.

The libraries in an SDK are stub libraries for linking only; they do not contain executable code but just the exported symbols. SDK support only works with native build targets.

SDK Settings

To use an SDK for an Xcode project, you make two selections among your project’s build settings:

• Choose a Base SDK to build your project. Your software can use features available in OS versions up to and including the one corresponding to the SDK you choose. If you don‚Äôt select an SDK, the default is to build for the current operating system.

  The Xcode build setting name for this parameter is SDKROOT (Base SDK).

• Choose a Deployment OS version. This identifies the earliest system version on which the software can run. By default, this is set to the version of the OS corresponding to the Base SDK version and later.

  The Xcode build setting names for this parameter are MACOSX_DEPLOYMENT_TARGET (Mac OS X Deployment Target) and IPHONEOS_DEPLOYMENT_TARGET (iOS Deployment Target).

For possible values and more information about build settings in Xcode, see Xcode Build Setting Reference and “Running Applications” in iOS Development Guide.

Xcode uses information from these settings when building and linking your software. You can unconditionally use features from OS versions up to and including the system version that you have specified as your Deployment OS version. You can use features from system versions later than the Deployment OS—up to and including the system version you've selected as your Base SDK—but you must check for the availability of the feature, as described in “Checking for Undefined Method and Function Calls.”

When you build your application, your Deployment OS version selection is reflected in the MinimumOSVersion entry in the application‚Äôs Info.plist file. For iOS applications, the App Store indicates the iOS release requirement for your application based on its MinimumOSVersion entry.

Figure 2-1 shows a timeline for a project with a Base SDK of Mac OS X version 10.6, with a Deployment OS version set to Mac OS X version 10.4. (The version numbers in the figure represent all releases of that version, including system updates.)

Figure 2-1  SDK development timeline

In this example, the software can freely use any features from Mac OS X versions 10.0 through 10.4. It can also take advantage of features from Mac OS X versions 10.5 and 10.6, but it must first check that the feature is available.

The effect of these settings at compile time and run time is a follows:

• If your code uses a symbol that is not defined in the selected Base SDK, you get a compile-time error.

• If your code uses a symbol that is defined in the selected Base SDK but is marked as deprecated, you get a compile-time warning.

• If your code uses a symbol that is defined in the selected Base SDK and in the selected Deployment OS version, your code builds and links normally. At run time:

  • On systems earlier than the Deployment OS version, your code may fail to load if you use symbols unavailable in that version.

  • On systems equal to or later than the Deployment OS version, your code will have null function pointers for symbols not supported in that version; it is up to your code to be prepared for this‚Äîfor an example see ‚ÄúChecking for Undefined Method and Function Calls.‚Äù

Of course, you should also check to see if you are using deprecated APIs; though still available, these APIs are not guaranteed to be supported in the future. The compiler can warn you about the presence of deprecated APIs, as described in “Finding Deprecated APIs.”

When you change the Base SDK setting, in addition to changing the headers and libraries your code builds against, Xcode adjusts the behavior of other features appropriately. For example, symbol lookup, code completion, and header file opening are based on the headers in the Base SDK, rather than those of the currently running system. Similarly, the Xcode Quick Help affinity mechanism ensures that documentation lookup uses the doc set corresponding to the Base SDK.

You can also set the Base SDK and Deployment OS version for any individual target in the project. Any value explicitly assigned to an individual target inspector overrides, for that target, the value assigned to that setting in the project inspector. (However, some Xcode features that attempt to correlate with the Base SDK setting, such as symbol definition and documentation lookup, may work differently.)

Configuring a Makefile-Based Project

If you have a makefile-based project, you can also take advantage of SDK-based development, by adding the appropriate options to your compile and link commands. Using SDKs in makefile-based projects requires GCC 4.0 or later. To choose an SDK, you use the -isysroot option with the compiler and the -syslibroot option with the linker. Both options require that you specify the full path to the desired SDK directory. To set the Deployment OS version in a makefile, use a makefile variable of the form: ENVP= MACOSX_DEPLOYMENT_TARGET=10.4. To use this variable in your makefile, include it in front of your compile and link commands.

Setting the Prefix File

Xcode supports prefix files, header files that are included implicitly by each of your source files when they're built. Many Xcode project templates generate prefix files automatically, including umbrella frameworks appropriate to the selected type of application. For efficiency, prefix files are precompiled and cached, so Xcode does not need to recompile many lines of identical code each time you build your project. You can add directives to import the particular frameworks on which your application depends.

If you are using SDK-based development, you must ensure that your prefix file that takes into account the selected SDK. That is, don‚Äôt set the prefix file to an umbrella header file using an absolute path, such as /System/Library/Frameworks/Cocoa.framework/Versions/A/Headers/Cocoa.h. This absolute path does not work because the specified header is from the current system, rather than the chosen SDK.

To include umbrella framework headers, add the appropriate #import <Framework/Framework.h> directives to your prefix file. With this technique, the compiler always chooses the headers from the appropriate SDK directory. For example, if your project is named TestSDK and it has a prefix file TestSDK_Prefix.pch, add the following line to that file:

#import <Cocoa/Cocoa.h>

If you are using Objective-C, it‚Äôs preferable to use the #import directive rather than #include (which you must use in procedural C programs) because #import guarantees that the same header file is never included more than once.