SDK Compatibility Guide ( 10000163 i 4.0.3)

juggleroffbeatMobile - Wireless

Jul 19, 2012 (5 years and 27 days ago)

644 views

SDKCompatibility Guide
Contents
Introduction 4
Organization of This Document 4
Overview of SDK-Based Development 5
Behavior Selection in Frameworks 5
Configuring a Project for SDK-Based Development 7
SDK Header Files and Stub Libraries 7
Base SDK and Deployment Target Settings 7
Weak Linking and Apple Frameworks 9
Configuring a Makefile-Based Project 10
Setting the Prefix File 11
Using SDK-Based Development 12
Using Weakly Linked Classes in iOS 12
Using Weakly Linked Methods,Functions,and Symbols 14
Weak Linking to an Entire Framework 15
Conditionally Compiling for Different SDKs 16
Finding Instances of Deprecated API Usage 17
Determining the Version of the Operating Systemor a Framework 18
Document Revision History 20
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
2
Figures and Listings
Configuring a Project for SDK-Based Development 7
Figure 2-1 SDK development timeline 8
Using SDK-Based Development 12
Listing 3-1 Checking the availability of an Objective-C method 14
Listing 3-2 Checking the availability of a C function 15
Listing 3-3 Using preprocessor directives for conditional compilation 16
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
3
Xcode includes software development kits (SDKs) that enable you to create applications that run on specific
versions of iOS or Mac OS X—including versions different fromthe one you are developing on.This technology
lets you build a single binary that takes advantage of newfeatures when running on a systemthat supports
them,andgracefully degrades whenrunningonanolder system.Some Apple frameworks automatically modify
their behavior based on the SDK an application is built against for improved compatibility.
Note This document does not explain howto develop code that runs on both the iOS and Mac OS
X platforms.Although Xcode enables you to switch platforms by simply choosing a different SDK,
there are fundamental design differences between iOS and Mac OS X programs.See “Migrating from
Cocoa” for more information.
Read this document if you want your application to target a specific version or multiple versions of iOS or Mac
OS X.
Organization of This Document
This document contains the following chapters:

“Overviewof SDK-Based Development” (page 5) describes howSDK-based development works.

“Configuring a Project for SDK-Based Development” (page 7) describes howto set up your project to
use an SDK.

“Using SDK-Based Development” (page 12) explains howto use weakly linked classes,methods,and
functions,howto weakly link an entire framework,howto compile conditionally for different SDKs,and
howto find uses of deprecated APIs in your code.
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
4
Introduction
Apple makes SDKs available for specific versions of iOS and Mac OS X.Using these SDKs allows you to build
against the headers and libraries of an operating systemversion other than the one you're running on.For
example,you can build for Mac OS X version 10.4 while running on Mac OS X version 10.6.
The Mac OS X SDKs are installed as part of the Xcode Essentials install package with Xcode 3.2 and later.Xcode
release notes list the SDKs supported by each release.When developing for iOS,you always use an SDK
downloaded fromthe iOS Dev Center website.
Take advantage of SDK-based development in these ways:

You can build a target optimized for one version of an operating systemand forward-compatible with
later versions,but doesn’t take specific advantage of newer features.

You can build a target for a range of operating systemversions,so that it can launch in older versions but
can take advantage of features in newer ones.This allows you to deliver software that provides newvalue
to customers who have upgraded to a newsystemversion,but still runs for those who haven’t.
To develop software that can be deployed on,and take advantage of features from,different versions of iOS
or Mac OS X,you specify which version—or SDK—of iOS or Mac OS X headers and libraries to build with.You
can also specify the oldest iOS or Mac OS X systemversion on which the software will run.These concepts are
described in “Base SDK and Deployment Target Settings” (page 7).
Behavior Selection in Frameworks
As frameworks evolve through various releases,APIs are introduced or deprecated and behaviors of existing
APIs may occasionally change.Apple makes every effort to minimize changes that may cause incompatibilities,
in some cases providing alternate behaviors based on the framework version.In rare cases,your code needs
to determine the framework version and adjust accordingly.
As a backward-compatibility mechanism,Apple frameworks sometimes check for the version of the SDK an
application is built against,and,if it is an older SDK,modify the behavior for compatibility.This is done in cases
where Apple predicts or discovers compatibility problems.
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
5
Overviewof SDK-Based Development
Note Most version-related behavior changes are listed in framework release notes,but they are not
necessarily described in the reference documentation.To understand the differences fromone
release to another,carefully reviewthe release notes.
Typically,frameworks detect howan application is built by looking at the version of the systemframeworks
the application is linked against.Thus,when relinking your application using a newer SDK,you might notice
different behaviors—some of which might cause incompatibilities.In these cases,because your application is
being rebuilt,you should address these issues at the same time.For this reason,if you are doing a small update
of your application,to address a fewbugs,for example,it's usually best to continue building with the same
build environment and libraries used originally;that is,against the original SDK.
In some cases,frameworks provide defaults (preferences) settings that you can use to get the old or new
behavior,independent of the SDK an application is built against.Often these preferences are provided for
debugging purposes only;in some cases the preferences can be used globally to modify the behavior of an
application by registering the values.If taking advantage of this mechanism,do it very early in your code,using
the NSUserDefaults method registerDefaults:).
Overviewof SDK-Based Development
Behavior Selection in Frameworks
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
6
This chapter describes the configuration of installed iOS and Mac OS X SDKs and explains howto set up your
Xcode project to use a particular SDK.
SDK Header Files and Stub Libraries
When you install Xcode,the installer creates a/Developer/SDKs directory.This directory contains one or
more subdirectories,each of which provides the complete set of header files and stub libraries that shipped
for a particular versionof iOS or Mac OS X.AMac OS XSDKis namedby major version,suchas MacOSX10.6.sdk,
but represents the latest minor version available for the major version.
The Xcode installer for iOS places SDKs in the/Developer/Platforms directory,within which is a directory
for eachplatform,suchas iPhoneOS.platform.Eachplatformdirectory,inturn,contains a Developer/SDKs
directory specific tothat platform.The iOS SDKs are namedby minor versions of iOS,suchas iPhoneOS4.2.sdk.
Choosingthe latest SDKfor your project lets youuse the newAPIs introducedinthe OS update that corresponds
to that SDK.When newfunctionality is added as part of a systemupdate,the systemupdate itself does not
typically contain updated header files reflecting the change.The SDKs,however,do contain updated header
files.
Each.sdk directory resembles the directory hierarchy of the operating systemrelease it represents:It has usr,
System,andDeveloperdirectories at its toplevel.Mac OS X.sdkdirectories alsocontaina Librarydirectory.
Each of these directories in turn contains subdirectories with the headers and libraries that are present in the
corresponding version of the operating systemwith Xcode installed.
The libraries in an iOS or Mac OS X SDK are stubs for linking only;they do not contain executable code but just
the exported symbols.SDK support works only with native build targets.
Base SDK and Deployment Target Settings
To use a particular SDK for an Xcode project,make two selections in your project’s build settings.These choices
determine which operating systemfeatures your project can use,as follows:

Choose a deployment target.This identifies the earliest OS version on which your software can run.By
default,Xcode sets this to the version of the OS corresponding to the base SDK version and later.
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
7
Configuring a Project for SDK-Based Development
The Xcode build variable names for this setting are MACOSX_DEPLOYMENT_TARGET (Mac OS X
Deployment Target) and IPHONEOS_DEPLOYMENT_TARGET (iOS Deployment Target).
You can unconditionally use features fromOS versions upto andincludingyour deployment target setting.

Choose a base SDK.Your software can use features available in OS versions up to and including the one
corresponding to the base SDK.By default,Xcode sets this to the newest OS supported by Xcode.
The Xcode build setting name for this parameter is SDKROOT (Base SDK).
You can use features fromsystemversions later than the deployment target—up to and including the OS
version you've selected as your base SDK—but you must check for the availability of newfeatures,as
described in “Using Weakly Linked Classes in iOS” (page 12) and “Using Weakly Linked Methods and
Functions” (page 14).
For possible values and more information about build settings in Xcode,see “Building for Multiple Releases of an
Operating System” in Xcode Project Management Guide,Xcode Build Setting Reference and “Running Applications”
in Tools WorkflowGuide for iOS.
When you build your application,your deployment target is reflected in the MinimumOSVersion entry in the
application’s Info.plistfile.For iOS apps,the MinimumOSVersionentry is usedby the AppStore to indicate
the iOS release requirement.
Figure 2-1 shows a timeline that explains the relationship between deployment target and base SDK.
Figure 2-1 SDK development timeline
Deployment target
10.4
10.5
10.6
Base SDK
Unconditionally use these APIs
Conditionally use these APIs Do not use these APIs
?10.0 10.3
Major versions
The figure describes a project with a deployment target of Mac OS X v10.4 and a base SDK of Mac OS X v10.6.
(The version numbers in the figure represent all releases of that version,including systemupdates.)
In this example,the software can freely use any features fromMac OS X v10.0 through the newest update of
version 10.4.It can conditionally take advantage of features fromMac OS X v10.5 and 10.6,after ensuring that
each such feature is available.
The effects of these settings at compile time and run time are as follows.If your code uses a symbol:

Not defined in the base SDK (for example,a symbol froma newer OS),you get a compile-time error.

Defined in the base SDK but marked as deprecated,you get a compile-time warning.
Configuring a Project for SDK-Based Development
Base SDK and Deployment Target Settings
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
8

Defined in the deployment target,your code links and builds normally.At run time:

On a systemrunning an OS earlier than the deployment target,your code may fail to load if you use
symbols unavailable in that OS.

On a systemrunning an OS equal to or later than the deployment target,your code has null pointers
for symbols not available in that OS.Prepare your code for this as described in “Using Weakly Linked
Methods and Functions” (page 14) and “Using Weakly Linked Classes in iOS” (page 12).
Note Mac OS X v10.6 does not support using iOS Simulator SDKs prior to version 3.0.In addition,
when building with Simulator SDKs,the binary runs only on the same operating systemversion as
the base SDK,not on earlier or later versions.
Always check to see if you are using deprecatedAPIs;though still available,deprecatedAPIs are not guaranteed
to be available in the future.The compiler warns you about the presence of deprecated APIs in your code,as
described in “Finding Instances of Deprecated API Usage” (page 17).
Whenyouchange the base SDKsetting,inadditiontochangingthe headers andstublibraries your code builds
against,Xcode adjusts the behavior of other features appropriately.For example,symbol lookup,code
completion,andheader file openingare basedonthe headers inthe base SDK,rather thanthose of the currently
running OS (if the two differ).Similarly,the Xcode Quick Help affinity mechanismensures that documentation
lookup uses the doc set corresponding to the base SDK.
In addition to setting the base SDK and deployment target for your project as a whole,you can set these values
individually for each build target.Target settings override project settings.(However,some Xcode features
that attempt to correlate with the base SDK setting,such as symbol definition and documentation lookup,
may work differently.)
Weak Linking and Apple Frameworks
The Xcode compiler uses availability macros,attachedtothe symbols inApple framework headers,todetermine
whether symbols are weakly or strongly linked.These macros state in which version of the operating system
a feature first appeared.For example,the macro in the following declaration indicates that the
enumerateObjectsUsingBlock:method (in the NSArray class) is available starting in Mac OS X v10.6 and
iOS 4.0:
- (void)enumerateObjectsUsingBlock:(void (^)(id obj,NSUInteger idx,BOOL
*stop))block NS_AVAILABLE(10_6,4_0);
Configuring a Project for SDK-Based Development
Weak Linking and Apple Frameworks
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
9
When a symbol in a framework is defined as weakly linked,the symbol does not have to be present at runtime
for a process to continue running.The static linker identifies a weakly linkedsymbol as such in any code module
that references the symbol.The dynamic linker uses this same information at run time to determine whether
a process can continue running.If a weakly linked symbol present in a code module is not present in the
framework,the code module can continue to run as long as it does not reference the symbol.If a weakly linked
symbol is present in its framework,the code can use it normally.
In the case of a deprecated symbol,the availability macro contains further syntax to indicate the version of
the operating systemin which the symbol was deprecated.In all cases,the reference documentation for a
symbol states its availability and,if applicable,its deprecation information.The availability macros are defined
in Availability.h and AvailabilityMacros.h in the/usr/include/directory.
The Xcode compiler interprets each availability macro in light of the base SDK and deployment target settings
for a project.The compiler uses these settings to assign appropriate values to the
MAC_OS_X_VERSION_MIN_REQUIRED and MAC_OS_X_VERSION_MAX_ALLOWED macros.
For example,suppose in Xcode you set the deployment target (minimumrequired version) to “Mac OS X
10.5” and the base SDK (maximumallowed version) to “Mac OS X 10.6”.During compilation,the compiler
would weakly link interfaces that were introduced in Mac OS X v10.6 while strongly linking interfaces defined
in earlier versions of the OS.This would allowyour application to run in Mac OS X v10.5 and take advantage
of newer features when available.
Important The deployment target setting in Xcode must be set to Mac OS X version 10.2 or later to take
advantage of weak linking.If you set this value to an earlier version of Mac OS X,you cannot use weak
linking in your project.When building for iOS,weak linking is available for all iOS versions.
Before using any symbol introduced in a version of iOS or Mac OS X that is later than your deployment target,
check whether the symbol is available.If the symbol is not available,provide an alternate code path.See “Using
SDK-Based Development” (page 12) for more information.
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 target 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.
Configuring a Project for SDK-Based Development
Configuring a Makefile-Based Project
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
10
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 selectedtype of application.For efficiency,prefix files are precompiledandcached,so Xcode
does not needtorecompile many lines of identical code eachtime youbuildyour project.Youcanadddirectives
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 fromthe current system,rather than the chosen SDK.
Toincludeumbrella framework headers,addtheappropriate#import <Framework/Framework.h>directives
to your prefix file.With this technique,the compiler always chooses the headers fromthe 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.
Configuring a Project for SDK-Based Development
Setting the Prefix File
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
11
This chapter describes SDK-based development techniques to use in your Xcode projects,explaining howyou
can:

Use weakly linkedclasses,methods,andfunctions tosupport runningonmultiple versions of anoperating
system

Weakly link an entire framework

Compile conditionally for different SDKs

Find uses of deprecated APIs in your code

Determine the operating systemversion,or a framework version,at run time
For background on weak linking,read “Weak Linking and Apple Frameworks” (page 9).
Using Weakly Linked Classes in iOS
If your Xcode project uses weakly linked classes,you must ensure the availability of those classes at run time
before using them.Attempting to use an unavailable class may generate a runtime binding error fromthe
dynamic linker,which may terminate the corresponding process.
Xcode projects that use a base SDK of iOS 4.2 or later should use the NSObject class method to check the
availability of weakly linked classes at run time.This simple,efficient mechanismtakes advantage of the
NS_CLASS_AVAILABLE class availability macro,available for most frameworks in iOS.
Important Check the most recent iOS Release Notes for the list of frameworks that do not yet support the
NS_CLASS_AVAILABLE macro.
For iOS frameworks that support the NS_CLASS_AVAILABLEmacro,conditionalize your code for weakly linked
classes as demonstrated in the following example:
if ([UIPrintInteractionController class]) {
//Create an instance of the class and use it.
} else {
//Alternate code path to follow when the
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
12
Using SDK-Based Development
//class is not available.
}
This works because if a weakly linked class is not available,sending a message to it is like sending a message
to nil.If you subclass a weakly linked class and the superclass is unavailable,then the subclass also appears
unavailable.
To use the class method as shown here,you need to do more than ensure that a framework supports the
NS_CLASS_AVAILABLE macro.You must also configure certain project settings.With these required settings
in place,the preceding code safely tests the availability of a class,even when running on a version of iOS in
which the class is not present.These settings are as follows:

The base SDK for your Xcode project must be iOS 4.2 or newer.The name for this setting in the build
settings editor is SDKROOT (Base SDK).

The deployment target for your project must be iOS 3.1 or newer.The name for this setting is
MACOSX_DEPLOYMENT_TARGET (Mac OS X Deployment Target).

The compiler for your project must be the LLVM-GCC 4.2 compiler or newer,or the LLVMcompiler (Clang)
1.5 or newer.The name for this setting is GCC_VERSION (C/C++ Compiler Version).

You must ensure that any frameworks not available in your project’s deployment target are weakly linked,
rather than required.See “Weak Linking to an Entire Framework” (page 15) and “Linking Libraries and
Frameworks” in Xcode Project Management Guide.
For information on using the Xcode build settings editor,see “Building Products” in Xcode Project Management
Guide.
In Mac OS X (and in iOS projects that do not meet the set of conditions just listed),you cannot use the class
method to determine if a weakly linked class is available.Instead,use the NSClassFromString function in
code similar to the following:
Class cls = NSClassFromString (@"NSRegularExpression");
if (cls) {
//Create an instance of the class and use it.
} else {
//Alternate code path to follow when the
//class is not available.
}
Using SDK-Based Development
Using Weakly Linked Classes in iOS
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
13
Using Weakly Linked Methods,Functions,and Symbols
If your project uses weakly linked methods,functions,or external symbols,you must ensure their availability
at run time before using them.If you attempt to use an unavailable item,the dynamic linker may generate a
runtime binding error and terminate the corresponding process.
Suppose you set the base SDK in your Xcode project to iOS 4.0.This allows your code to use features in that
version of the operating systemwhen running in that version.Suppose also that you want your software to
run in iOS 3.1,even though it cannot use the newer features in that version of the OS.Allowthis by setting
the deployment target to the earlier version of the operating system.
InObjective-C,the instancesRespondToSelector:methodtells youif a givenmethodselector is available.
For example,to use the availableCaptureModesForCameraDevice:method,first available in iOS 4.0,
you could use code like the following:
Listing 3-1 Checking the availability of an Objective-C method
if ([UIImagePickerController instancesRespondToSelector:
@selector (availableCaptureModesForCameraDevice:)]) {
//Method is available for use.
//Your code can check if video capture is available and,
//if it is,offer that option.
} else {
//Method is not available.
//Alternate code to use only still image capture.
}
Whenyour code runs iniOS 4.0or later,it cancall availableCaptureModesForCameraDevice:todetermine
if video capture is available on the device.When it runs in iOS 3.1,however,it must assume that only still image
capture is available.
If you were to build this code with various settings,you would see the following results:

If you specify a base SDK setting of iphoneos3.1:
The build would fail because the availableCaptureModesForCameraDevice:method is not defined
in that systemversion.

If you specify a base SDK setting of iphoneos4.0,and then set the deployment target to:

iphoneos4.0:The software would run only in iOS 4.0 or later and would fail to launch on earlier
systems.
Using SDK-Based Development
Using Weakly Linked Methods,Functions,and Symbols
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
14

iphoneos3.1:The software would run in iOS 4.0 and in iOS 3.1,but would fail to launch on earlier
systems.When running in iOS 3.1,the software would use the alternate code to capture images.
Check the availability of an Objective-C property by passing the getter method name (which is the same as
the property name) to instancesRespondToSelector:.
To determine if a weakly linkedCfunction is available,use the fact that the linker sets the address of unavailable
functions to NULL.Check a function’s address—and hence,its availability—by comparing the address to NULL
or nil.For example,before usingthe CGColorCreateGenericCMYKfunctionina project whose deployment
target is earlier than Mac OS X v10.5,use code like the following:
Listing 3-2 Checking the availability of a C function
if (CGColorCreateGenericCMYK!= NULL) {
CGColorCreateGenericCMYK (0.1,0.5.0.0,1.0,0.1);
} else {
//Function is not available.
//Alternate code to create a color object with earlier technology
}
Note To check the availability of a function,explicitly compare its address to NULL or nil.You
cannot use the negation operator (!) to negate the address of a function to check its availability.
Also,note that the name of a C function is synonymous with its address.That is,&myFunction is
equivalent to myFunction.
Check the availability of an external (extern) constant or a notification name by explicitly comparing its
address—and not the symbol’s bare name—to NULL or nil.
Weak Linking to an Entire Framework
If you are using a recently added framework—one that became available after your deployment target—you
must explicitly weak link to the framework itself.For example,say youwant to link to the Accelerate framework,
first available in iOS 4.0,to use its features on systems in which they’re available.In addition,say you set your
deployment target to iOS 3.1.3,allowing users of that version of iOS to use your app without the newfeatures.
In this example,you must weak link to the Accelerate framework.
When using a framework that is available in your deployment target,you should require that framework (and
not weakly link it).
Using SDK-Based Development
Weak Linking to an Entire Framework
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
15
For information on howto weakly link to a framework,refer to “LinkingLibraries andFrameworks” in Xcode Project
Management Guide.
Conditionally Compiling for Different SDKs
If you use one set of source code to build for more than one base SDK,you might need to conditionalize for
the base SDK in use.Do this by using preprocessor directives with the macros defined in Availability.h.
Note The Availability.h header is for targeting iOS and for targeting Mac OS X v10.6 and later.
The older AvailabilityMacros.h header was introduced in Mac OS X v10.2.These files reside in
the/usr/include directory.
Suppose you want to compile the code shown in Listing 3-2 using a base SDK setting of macosx10.4.The
portion of the code that refers to the CGColorCreateGenericCMYK function—introduced in Mac OS X
v10.5—must be masked during the build.This is because any reference to the unavailable
CGColorCreateGenericCMYK function would cause a compiler error.
To allowthe code to build,use the __MAC_OS_X_VERSION_MAX_ALLOWED macro to:

Ensure that the project’s target is Mac OS X and not iOS

Hide code that is unavailable in the base SDK
The following code excerpt demonstrates this.Notice the use of the numerical value 1050 instead of the
symbol __MAC_10_5 in the#if comparison clause:If the code is loaded on an older systemthat does not
include the symbol definition,the comparison still works.
Listing 3-3 Using preprocessor directives for conditional compilation
#ifdef __MAC_OS_X_VERSION_MAX_ALLOWED
//code only compiled when targeting Mac OS X and not iOS
//note use of 1050 instead of __MAC_10_5
#if __MAC_OS_X_VERSION_MAX_ALLOWED >= 1050
if (CGColorCreateGenericCMYK!= NULL) {
CGColorCreateGenericCMYK(0.1,0.5.0.0,1.0,0.1);
} else {
#endif
//code to create a color object with earlier technology
Using SDK-Based Development
Conditionally Compiling for Different SDKs
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
16
#if __MAC_OS_X_VERSION_MAX_ALLOWED >= 1050
}
#endif
#endif
}
In addition to using preprocessor macros,the preceding code also assumes that the code could be compiled
using a newer base SDK but deployed on a computer running Mac OS X v10.4 and earlier.Specifically,it checks
for the existence of the weakly linked CGColorCreateGenericCMYK symbol before attempting to call it.This
prevents the code fromgenerating a runtime error,which can occur if you build the code against a newer SDK
but deploy it on an older system.For more information about instituting runtime checks to determine the
presence of symbols,see “Using Weakly Linked Classes in iOS” (page 12) and “Using Weakly Linked Methods
and Functions” (page 14).
Finding Instances of Deprecated API Usage
As iOS and Mac OS X evolve,the APIs and technologies they encompass are sometimes changed to meet the
needs of developers.As part of this evolution,less efficient interfaces are deprecated in favor of newer ones.
Availability macros attached to declarations in header files help you find deprecated interfaces.Reference
documentation also flags deprecated interfaces.
Note Deprecation does not mean the immediate deletion of an interface froma framework or
library.It is simply a way to flag interfaces for which better alternatives exist.You can use deprecated
APIs in your code.However,Apple recommends that you migrate to newer interfaces as soon as
possible because deprecated APIs may be deleted froma future version of the OS.Check the header
files or documentation of the deprecated API for information about any recommended replacement
interfaces.
If youcompile a project witha deployment target of Mac OS Xv10.5 anduse aninterface taggedas deprecated,
the compiler issues a corresponding warning.The warning includes the name of the deprecated interface and
where in your code it was used.For example,if the HPurge function were deprecated,you would get an error
similar to the following:
'HPurge'is deprecated (declared at/Users/steve/MyProject/main.c:51)
To locate instances of deprecated API use in your code,look for warnings of this type.If your project has many
warnings,use the search field in Xcode to filter the warnings list based on the “deprecated” keyword.
Using SDK-Based Development
Finding Instances of Deprecated API Usage
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
17
Determining the Version of the Operating Systemor a Framework
In rare instances,checking the run time availability of a symbol is not a complete solution.For example,if the
behavior of a method changed fromone OS version to another,or if a bug was fixed in a previously available
method,it’s important to write your code to take those changes into account.
The technique to use for checking operating systemversion depends on your target platform,as follows:

To check the version of iOS at run time,use code like this:.
NSString *osVersion = [[UIDevice currentDevice] systemVersion];

To check the version of Mac OS X at run time,use the Gestalt function and the SystemVersion Selectors
constants.
Alternatively,for many frameworks,you can check the version of a specific framework at run time.To do this,
use global framework-version constants—if they are provided by the framework.For example,the Application
Kit (in NSApplication.h) declares the NSAppKitVersionNumber constant which you can use to detect
different versions of the Application Kit framework:
APPKIT_EXTERN double NSAppKitVersionNumber;
#define NSAppKitVersionNumber10_0 577
#define NSAppKitVersionNumber10_1 620
#define NSAppKitVersionNumber10_2 663
#define NSAppKitVersionNumber10_2_3 663.6
#define NSAppKitVersionNumber10_3 743
#define NSAppKitVersionNumber10_3_2 743.14
#define NSAppKitVersionNumber10_3_3 743.2
#define NSAppKitVersionNumber10_3_5 743.24
#define NSAppKitVersionNumber10_3_7 743.33
#define NSAppKitVersionNumber10_3_9 743.36
#define NSAppKitVersionNumber10_4 824
#define NSAppKitVersionNumber10_4_1 824.1
#define NSAppKitVersionNumber10_4_3 824.23
#define NSAppKitVersionNumber10_4_4 824.33
#define NSAppKitVersionNumber10_4_7 824.41
#define NSAppKitVersionNumber10_5 949
#define NSAppKitVersionNumber10_5_2 949.27
Using SDK-Based Development
Determining the Version of the Operating Systemor a Framework
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
18
#define NSAppKitVersionNumber10_5_3 949.33
You can compare against this constant’s value to determine which version of the Application Kit your code is
running against.One typical approach is to floor the value of the global constant and check the result against
the constants declared in NSApplication.h.For example:
if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_0) {
/* On a 10.0.x or earlier system */
} else if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_1) {
/* On a 10.1 - 10.1.x system */
} else if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_2) {
/* On a 10.2 - 10.2.x system */
} else if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_3) {
/* On 10.3 - 10.3.x system */
} else if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_4) {
/* On a 10.4 - 10.4.x system */
} else if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_5) {
/* On a 10.5 - 10.5.x system */
} else {
/* 10.6 or later system */
}
Similarly,Foundation (in NSObjCRuntime.h) declares the NSFoundationVersionNumber global constant
and specific values for each version.
Some individual headers for other objects and components may also declare the version numbers for
NSAppKitVersionNumber where some bug fix or functionality is available in a given update.
Using SDK-Based Development
Determining the Version of the Operating Systemor a Framework
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
19
This table describes the changes to SDK Compatibility Guide.
NotesDate
Added an explanation of howto use the NS_CLASS_AVAILABLE macro
in “Using Weakly Linked Classes in iOS” (page 12).
2010-11-15
Updated and improved the “Configuring a Project for SDK-Based
Development” (page 7) and “Using SDK-Based Development” (page 12)
chapters.
Improved the “Using Weakly Linked Methods,Functions,and
Symbols” (page 14) section by adding information on checking the
availability of external symbols.
Corrected an example that shows howto use conditional compilation
macros.
2010-02-16
Clarified build setting information.2009-09-09
Changed the title fromCross-Development Programming Guide.Added
information about iOS SDK-baseddevelopment.Revisedtext significantly
and removed obsolete information.
2009-05-12
Added details on cross-development and universal binaries.2006-11-07
Added chapter “Determining the Version of a Framework”.Noted
requirement to build with GCC 3.3 when targeting Mac OS X versions
prior to Mac OS X v10.3.0.Corrected Mac OS X version requirements for
code compiled with GCC 4.0.Added links to further information on
buildinguniversal binaries fromthe commandline.Changeddeployment
target in example.
Corrected a build-setting specification and added
per-architecture-build-setting availability details.
2006-05-23
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
20
Document Revision History
NotesDate
Corrected specification for LDFLAGS build setting in “Configuring a
Makefile-Based Project”.Added availability details for the per-architecture
build settings feature.
Added a link to Technical Note TN2163,which describes howto develop
a universal I/O Kit driver.
2006-03-08
Made minor corrections.2006-02-07
Added information on building universal binary versions of kernel
extensions.
Clarified use of LDFLAGS.
Added a section on using cross-development to create universal binaries.
Added information on identifying deprecated API.Corrected errors.
2005-11-09
Added “Cross-Development and Universal Binaries” chapter.Added
“Finding Instances of Deprecated API Usage” (page 17).Reorganized
content to create separate sections for configuring cross-development
settings in Xcode and in makefile-based projects.Corrected sample code
listing in “Conditionally Compiling for Different SDKs” (page 16).
Fixed a bug in code that checks for the existence of a symbol.Updated
steps for setting a deployment target to reflect Xcode 2.1.
2005-08-11
Updated information about checking for undefined functions.Added
information about howto support SDKs fromcommand-line programs.
2005-06-04
Made a number of changes throughout this document to reflect the final
status of cross-development support as it shipped in Mac OS X version
10.3.
2003-09-16
First general release of document.2003-08-21
Document Revision History
2010-11-15 | © 2010 Apple Inc. All Rights Reserved.
21
Apple Inc.
© 2010 Apple Inc.
All rights reserved.
No part of this publication may be reproduced,
storedina retrieval system,or transmitted,inany
formor by any means,mechanical,electronic,
photocopying,recording,or otherwise,without
prior written permission of Apple Inc.,with the
following exceptions:Any person is hereby
authorized to store documentation on a single
computer for personal use only and to print
copies of documentation for personal use
provided that the documentation contains
Apple’s copyright notice.
The Apple logo is a trademark of Apple Inc.
No licenses,express or implied,are granted with
respect toany of the technology describedinthis
document.Apple retains all intellectual property
rights associated with the technology described
in this document.This document is intended to
assist application developers to develop
applications only for Apple-labeled computers.
Apple Inc.
1 Infinite Loop
Cupertino,CA 95014
408-996-1010
App Store is a service mark of Apple Inc.
Apple,the Apple logo,Cocoa,eMac,iPhone,Mac,
Mac OS,Objective-C,OS X,and Xcode are
trademarks of Apple Inc.,registeredin the United
States and other countries.
IOS is a trademark or registered trademark of
Cisco in the U.S.and other countries and is used
under license.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED,WITHRESPECT TOTHIS
DOCUMENT,ITS QUALITY,ACCURACY,
MERCHANTABILITY,OR FITNESS FOR A PARTICULAR
PURPOSE.ASARESULT,THISDOCUMENTISPROVIDED
“AS IS,” AND YOU,THE READER,ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
INDIRECT,SPECIAL,INCIDENTAL,ORCONSEQUENTIAL
DAMAGES RESULTING FROMANY DEFECT OR
INACCURACY IN THIS DOCUMENT,even if advised of
the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS,ORAL
OR WRITTEN,EXPRESS OR IMPLIED.No Apple dealer,
agent,or employee is authorized to make any
modification,extension,or addition to this warranty.
Some states do not allowthe exclusion or limitation
of implied warranties or liability for incidental or
consequential damages,so the above limitation or
exclusion may not apply to you.This warranty gives
you specific legal rights,andyou may also have other
rights which vary fromstate to state.