A. Some Build Variables
This appendix offers a brief (though you may not believe it) list of the major build variables that control the Xcode build system. Build variables determine compiler flags, search paths, installation behavior, and essential information like product names. A comprehensive explanation of Xcode’s build variables can be found in the Documentation browser by searching for Build Setting Reference.
You can see all the build variables that are available to Run Script build phases by creating a phase that consists of only one line like echo, then checking Show environment variables in build log. Do a build, find the build at the top of the Log navigator (eighth tab), and select the All and All Messages filters. Click the script phase, and then on the lines-of-text button that appears at the right end of the row.
You’ll find there are nearly 350 variables. This appendix lists the more useful ones. For the purposes of example, the conditions of the build are those shown in Table A.1.
I’ve chosen distinct names so you can identify the origins of the automatically set variables. The templates start projects with the main target, scheme, and product name having the same values. You wouldn’t ordinarily change that, but it is possible. I did leave the target and build scheme names the same, because the build system never sees scheme names. Schemes merely organize build configurations for targets; the configurations and their settings are what matter to the build system, not how they were selected.
Some of these settings have no corresponding interface in the Build Settings tabs of the Target or Project editor. You can set these—if they are not read-only—by selecting Editor → Add Build Setting → Add User-Defined Setting. Xcode will add a new line to the list, and you can enter the setting’s name in the Setting column and the value under the level at which you want to set it. Boolean values should be entered as YES or NO.
The authoritative name for a build variable is its “setting name”—the name of the actual build variable, as visible in environment variables and substitutable into other settings and Info.plist expansions. You can find the corresponding entries in a Build Settings tab by typing the setting name, plain-language name, or any part of the long-form description into the tab’s search field.
Note
Settings can be made conditional according to what processor architecture the product is being built for or what SDK is being used. See Chapter 25, “The Xcode Build System,” for details.
The Build Settings tab can display setting names instead of the plain-language “setting titles.” The Show Setting Names/Show Setting Titles item in the Editor menu toggles between the “real” names and the descriptive titles.
Similarly, you can control how setting values are displayed. A setting may be defined in terms of another setting, as when you specify an installation directory by $(HOME)/Applications. By default, Xcode displays embedded build variables by expanding them, because the build system will see only the fully expanded strings. The Show Definitions/Show Values (for the unexpanded value expressions) item in the Editor menu changes the display so that variable references are shown either literally (Definitions) or as interpreted (Values).
Useful Build Variables
With no further ado, here is a list of selected build variables. I’ve grouped them by general function, and then by a rough general-to-specific order within those groups.
Some of these variables appear to be obsolete: Apple no longer documents them, and the target templates no longer use them by default. The build system still sets them as environment variables, presumably to preserve compatibility with old run-script build phases, but the best bet is not to use them for new development.
Others are obviously used, but Xcode does not expose predefined descriptions or defaults for them. Often, these settings must have values that are strictly derived from other settings, and overriding them would break the build.
Environment
These are read-only variables that you can use in scripts or to build up other build settings.
PROJECT—The name of the Xcode project, without extension. Unless you override it, PROJECT_NAME follows this setting.
(PasserRating)
ACTION—The name of the xcodebuild action that was entered in the command line or generated by Xcode to match the Product action that triggered the build.
(build)
PROJECT_NAME—The name of the project that contains the target that is being built. Most intermediate and project paths go through a directory with this name.
PLATFORM_NAME—The name of the target platform, macosx, iphonesimulator, or iphoneos. This setting appears to be obsolete; Apple no longer documents it.
(macosx)
PRODUCT_NAME—The name of the target package and binary, unadorned by prefixes, suffixes, or extensions.
(Passer Rating)
FULL_PRODUCT_NAME—The file or directory name of the target package.
(Passer Rating.app)
PRODUCT_TYPE—A reverse-DNS-style identifier for the kind of product the target produces. This defines the endpoint in the build process, from which the build system infers all the steps necessary to generate the product.
(com.apple.product-type.application)
HOME—The path to your home directory, just as it would be in bash.
USER—The user name of the person doing the build. There is a corresponding UID variable for the numeric user ID.
GROUP—The group name of the person doing the build. There is a corresponding GID variable for the numeric group ID.
PATH—The standard Unix PATH environment variable, specifying the order in which directories should be searched when Unix commands are invoked. (various paths to Xcode’s toolchain and shadow bin and libexec directories; followed by the standard directories in the general filesystem)
MAC_OS_X_VERSION_ACTUAL—A six-digit number designating the version of OS X on which the build is being done. The first two digits will be 10, the next 10, and the last, the minor version. The format changed with Yosemite; before, the setting was 10, followed by one each for the major and minor versions.
(101002)
MAC_OS_X_VERSION_MAJOR—A six-digit number that is the same as MAC_OS_X_VERSION_ACTUAL, but with the minor set to zero.
(101000)
MAC_OS_X_VERSION_MINOR—A four-digit number that designates the current OS version, omitting the leading 10. In Yosemite, the first two digits will always be 10; the second two are the minor version.
(1002)
MAC_OS_X_PRODUCT_BUILD_VERSION—The build number for the current OS.
(14Cnnn)
XCODE_VERSION_ACTUAL
(0620),
XCODE_VERSION_MAJOR
(0600),
and XCODE_VERSION_MINOR
(0620)–This is the same version information as in the MAC_OS_X_VERSION settings, but for Xcode itself.
Code Signing
These settings control provisioning issues, including the selection of the provisioning profile and the signing identity.
AD_HOC_CODE_SIGNING_ALLOWED—Controls whether an ad hoc distribution profile will be accepted for this build.
(NO)
CODE_SIGN_IDENTITY—The signing identity to be used for the build. This may be in a reduced form such as iPhone Developer or iPhone Distribution. If so, the build system will consult the provisioning profile for the full common name of the required certificate.
You should not explicitly set the identity if you can avoid it: Otherwise, team members will force their own certificates, and then check the project into source control. The other team members get project files that require a certificate they don’t have. This sets off an arms race in which developers compete to jam their own certificates into the common project file.
Use the generic identities. Xcode will figure it out. If it can’t, you have a provisioning problem that will probably get worse when you start building for distribution. It’s hard to fix, but you have to do it.
(iPhone Developer)
CODE_SIGNING_ALLOWED—Signify whether the code-signing step will be performed at all. The “allowed” switch must be YES before “required” is even considered.
(NO)
CODE_SIGN_ENTITLEMENTS—The path to the .entitlements plist claiming permission to use certain privileged services, relative to the project folder.
(Passer Rating Target/Passer Rating.entitlements)
CODE_SIGN_RESOURCE_RULES_PATH—The path to a property list that directs codesign to ignore some files in the product package, so as not to freeze files that have to be modified after signing.
OTHER_CODE_SIGN_FLAGS—Identifies any additional command-line flags you need to pass to codesign. You usually don’t want to change Xcode’s choice of settings for iOS builds, or for Mac builds destined for Developer ID or the Mac App Store.
PROVISIONING_PROFILE—This was the UUID of a valid provisioning profile that matches the bundle ID set in Info.plist. New targets will not set this; Xcode will find the correct profile on the basis of the application ID and the signing identity you choose. There’s no point in setting the profile independently, as anything other than the one that matches is in error.
Locations
Source Locations
PROJECT_DIR—The directory that contains the project file.
(/Users/fritza/Desktop/PasserRating)
PROJECT_FILE_PATH—The full path to the project file.
(/Users/fritza/Desktop/PasserRating/PasserRating.xcodeproj)
SDKROOT—The root of the tree in which to search for system headers and libraries; this is simple for OS X SDKs, but it gets more involved once you get into the platform and OS options in the iOS SDK. This should be the same as SDK_DIR, and the last component should be the same as the base name in SDK_NAME.
(/Applications/Xcode.app/.../iPhoneSimulator8.2.sdk)
SRCROOT—The folder containing the source code for the project, usually the project document’s directory. SOURCE_ROOT is a synonym.
(/Users/fritza/Desktop/PasserRating)
Destination Locations
These are the directories to which object files, derived files, and products are directed in the course of a build. Many of these are somewhere in the “derived-data” directory for your project. You can set that directory using the File → Project (or Workspace) Settings. . . command, in the Build tab, but typically you’ll use the default directory, within the Library folder of your home directory. The path to the default directory goes deep and involves a unique identifier string, so it’s not practical for me to spell out in this list; you can depend on its beginning with the name of your target. If you see a path beginning with /Users/fritza/Library, you can assume that it’s the derived-data directory.
The whole idea of the derived-data directory is to put all the files—they are many and large—that Xcode generates in managing and building your projects, all in one place. These files are “derived” in that they contain only information that can be reconstructed from your source files and settings. You do not want to put derived files in your project directory tree if you intend to share it or put it under revision control. If you must put the derived-data directory in your project directory, make sure to give it a name you can match in the ignored-files patterns in your Subversion or Git configuration.
If you want to inspect the derived-data directory, open the Organizer (Window → Organizer), and select the Projects panel. Find your project in the list on the left, and see the panel at the top of the detail view. The full path to the directory will be shown (middle-truncated if the window is too narrow). Next to it will be a small arrow button that will show the directory in the Finder.
OBJROOT—The folder containing, perhaps indirectly, the intermediate products, such as object files, of the build. Unless you override the location for intermediate files, this folder will be buried deep in your user Library directory.
(/Users/fritza/Library/Developer/Xcode/DerivedData/ /Passer
Rating-. . . /Intermediates)
SYMROOT—The container for folders that receive symbol-rich, meaning not-yet-stripped, versions of the product. This, too, is buried in your own Library directory.
(/Users/fritza/Library/Developer/-. . . /ArchiveIntermediates/
/Passer Rating/-BuildProductsPath)
DSTROOT—The directory into which the product will be “installed.” For iOS targets, this is simply a holding directory. For OS X, it is usually in the /tmp tree, and the project will make and populate subdirectories in DSTROOT as though it were the root of your filesystem. It is relevant only in install builds. Nowadays, it’s useful only if you’re building and testing system or kernel software.
(/tmp/Passer Rating.dst)
BUILT_PRODUCTS_DIR—The full path to the directory that receives either every product of the project or, if the products are scattered, symbolic links to every product. A script can therefore depend on reaching all of the products through this path. By default, $(SYMROOT)/$(CONFIGURATION), and therefore deep within your Library directory. CONFIGURATION_BUILD_DIR is a synonym.
(/Users/fritza/Library/Developer/-Xcode/DerivedData/
/Passer Rating-. . . /Build/Products/Debug-iphonesimulator)
TARGET_BUILD_DIR—The directory into which the product of the current target is built.
(/Users/fritza/Library/Developer/-Xcode/DerivedData/
Passer Rating-... /Build/Products/Debug-iphonesimulator)
DERIVED_FILE_DIR—The directory that receives intermediate source files generated in the course of a build, such as the sources generated by the bison parser generator. This variable is paralleled by DERIVED_FILES_DIR and DERIVED_SOURCES_DIR. If you have a more general need for a place to put a temporary file, consult the Xcode documentation for PROJECT_TEMP_DIR or TARGET_TEMP_DIR.
(/Users/fritza/Library/Developer/. . . /Build/Intermediates/
Passer Rating.build/Debug-iphonesimulator/Passer
Rating.build/DerivedSources)
OBJECT_FILE_DIR—The directory containing subdirectories, one per architecture, containing compiled object files. It’s in the derived-data folder, which by default is deep within your Library directory.
(/Users/fritza/Library/Developer/. . . /Build/Intermediates/
Passer Rating Target.build/Debug-iphonesimulator/Passer
Rating.build)
SKIP_INSTALL—If NO, the build system will take all actions necessary to distribute the build products in their final directory locations. In practice, there is no actual installation; the “installation” tree is confined to an Xcode archive package. Exporting the archive will merge the tree into whatever root you choose.
If you want to create a stand-alone framework, you must set SKIPINSTALL to NO; otherwise the framework will exist only as a partially built temporary in the derived-products directory, for the use of other products while they are in development.
(NO)
Bundle Locations
If the product is a bundle, like an application or a framework, WRAPPER_NAME is the base name of the bundle directory.
(Passer Rating)
WRAPPER_EXTENSION and WRAPPER_SUFFIX—The extension and extension-with-dot for the bundle directory, if the target is a bundle.
(app and .app)
If SHALLOW_BUNDLE is YES, the other settings in this section are moot, because the product bundle is like an iOS application—all of the files, except for localizations, are to be found immediately inside the bundle directory, without the OS X bundle structure.
(YES)
CONTENTS_FOLDER_PATH—The path, within the target build directory, that contains the structural directories of a bundle product.
(Passer Rating.app)
EXECUTABLE_FOLDER_PATH—The path, in a bundle target in the target build directory, into which the product’s executable file is to be built. Not to be confused with EXECUTABLES_FOLDER_PATH, which points to a directory for “additional binary files,” named Executables.
(Passer Rating.app)
EXECUTABLE_PATH—The path, within TARGET_BUILD_DIR, to the executable binary.
(Passer Rating.app/Passer Rating)
FRAMEWORKS_FOLDER_PATH—The path, in a bundle target in the target build directory, that contains frameworks used by the product. This is set for iOS builds even though you can’t have a framework in an iOS application. For MyMacApp.app, it would be MyMacApp.app/Contents/Frameworks. There are variables for other possible bundle directories; see the Xcode documentation for more.
(Passer Rating.app/Frameworks)
UNLOCALIZED_RESOURCES_FOLDER_PATH—The directory, within a bundle product in the target build directory, that receives file resources that have no localization—not even the base localization. For MyMacApp.app, it would be MyMacApp.app/Contents/Resources.
(Passer Rating.app)
Compiler Settings
These settings control how the build system produces executable code. Many of these have the prefix CLANG_ or GCC_, even though gcc is no longer included in Apple’s developer tools, substituting clang. They carry over the prefix for backward compatibility.
Note
While the build variables expose a great number of clang settings, bear in mind that your scripts will have read-only access to them; any changes you make won’t be visible outside your script. The GCC_ and CLANG_ variables are primarily useful as substitutes into other build settings, including those you might create yourself. You might, for instance, assign a setting string to a preprocessor variable in GCC_PREPROCESSOR_DEFINITIONS so you could experiment with compiler settings and permit your code to print the build settings directly.
ARCHS—The CPU architectures for which Xcode is to generate product code. These must come from among the VALID_ARCHS list; by default, this is the value of ARCHS_STANDARD. (See Chapter 25, “The Xcode Build System,” for how the build system handles multiple-architecture products.) Note that iOS apps bound for the simulator will use your Mac’s hardware, so this setting will point to an Intel processor.
(x86_64)
ARCHS_STANDARD—The default set of architectures Xcode will build for.
(i386 x86_64)
ARCHS_STANDARD_32_BIT
(i386), ARCHS_STANDARD_64_BIT
(x86_64), and ARCHS_STANDARD_32_64_BIT
(i386 x86_64)—The standard architectures you’d use instead of ARCHS_STANDARD if you’re particular about whether the target should be 64-bit, 32-bit, or both.
NATIVE_ARCH—The architecture on which the current build is taking place. This is the same as CURRENT_ARCH and (if the target is OS X) NATIVE_ARCH_ACTUAL. Note that you can’t really use CURRENT_ARCH in a script—Run Script build phases are run only once per build, so the value you see for CURRENT_ARCH is only one of the architectures that will actually be built. If your script must hit every architecture being targeted, have it iterate through ARCHS.
(i386)
NATIVE_ARCH_32_BIT and NATIVE_ARCH_64_BIT—These are like NATIVE_ARCH, but refer to the 32-bit and 64-bit variants of the development architecture. On an iOS build, these settings are moot—they are the respective Intel architectures.
(i386 and x86_64)
CLANG_CXX_LANGUAGE_STANDARD—The dialect of C++ clang should accept.
(gnu++0x)
CLANG_ENABLE_MODULES—Whether C-family languages should accept @module directives, and in turn should be compiled into modules. Swift code always uses modules.
(YES)
DEFINES_MODULE—Whether the code generated by the build will constitute a module.
(NO)
MODULE_NAME—The name of the module the generated code defines. (empty—not defining a module)
PRODUCT_MODULE_NAME—The name of the module the generated code will be sorted into. This is important now that APIs and Swift code are all segregated into by-module namespaces.
(Passer_Rating)
CLANG_ENABLE_OBJC_ARC—Whether clang should generate Automatic Reference Counting code, and enforce ARC conventions, for Objective-C code. Swift code always uses ARC.
(YES)
GCC_OPTIMIZATION_LEVEL—The strategy clang is to use in rearranging the code it generates for efficiency, by one measure or another. The possible values include -O0 a literal translation, best for debugging; -O3, the most while still maintaining standards compliance; -Ofast, “aggressive,” going for speed at the possible sacrifice of standards compliance; and -Os, “fastest, smallest,” which will probably be fastest of all, because the other methods generate much more code, which will likely overrun the processor’s code cache and introduce halts to wait for code to load from memory.
(0)
SWIFT_OPTIMIZATION_LEVEL—The optimization strategy for Swift. The levels are -Onone, no optimization, best for debugging; -O, optimized as much as possible while maintaining runtime consistency checks; -Ounchecked, with all the consistency checks removed. Gamble on releasing an -Ounchecked product only after you’ve exhausted every possible means to trigger a check in -Onone code, and again with -Ounchecked.
(-Onone)
GCC_VERSION and GCC_VERSION_IDENTIFIER—The compiler version to use, which is fixed at Apple clang 1.0; there have been no backward-compatibility issues so far. The difference between the two is that the identifier uses underscores instead of dots.
(com.apple.compilers.llvm.clang.1_0)
GCC_PREPROCESSOR_DEFINITIONS—A space-separated list of symbols to be defined in all compilations. Items of the form symbol=value assign values to the symbols. Symbols defined in this way will be incorporated in precompiled headers. Related is GCC_PREPROCESSOR_DEFINITIONS_NOT_USED_IN_PRECOMPS, which specifies symbols defined in every compilation but not incorporated in precompiled headers. This allows you to share precompiled headers between build configurations, with variants in global definitions taken as options in the respective configurations. Swift will accept preprocessor symbols for testing by preprocessing directives like #if. The directives accept only simple values; they will not do any expansions the way C-family languages expand macros. If you want to define these, add -D symbol to OTHER_SWIFT_FLAGS.
(DEBUG=1)
GCC_ENABLE_OBJC_GC—Controls whether the project compiles Objective-C source with support for garbage collection. This setting is no longer available in the Build Settings editor, as Apple forbids garbage collection in all new development.
It’s good practice to treat a build as failed even if the only issues were warnings, not errors: Even if an executable binary could be generated, it won’t be. GCC_TREAT_WARNINGS_AS_ERRORS isn’t set by default, but maybe it should be; in most cases, warnings point out logical mistakes that you’ll have to debug anyway.
(NO)
GCC_WARN_INHIBIT_ALL_WARNINGS—The inverse of GCC_TREAT_WARNINGS_AS_ERRORS. clang won’t emit any warning messages. If doing this seems to you like a good idea, please warn your customers.
OTHER_CFLAGS, OTHER_CPLUSPLUSFLAGS, and OTHER_SWIFT_FLAGS—Catchall variables for compiler options that do not have their own build variables for C or Swift compilation. OTHER_SWIFT_FLAGS is the only way you can set preprocessor symbols for Swift code.
Apple tries to incorporate every reasonable flag in the Build Settings tab, so you should rarely need to use this setting. It’s a good idea to type a flag into the settings tab’s search field to see whether a direct setting is available. For linker flags, the equivalent is OTHER_LDFLAGS (empty).
GCC_WARN . . .—clang accepts a lot of warning flags, and most of them have equivalents in the build variables. Click around in the Build Settings tab with the Quick Help inspector (Utility area, on the right, second tab) to see what the warnings do and what the build-variable equivalent is.
Many developers use -Wall as a shortcut for a comprehensive set of warnings, and the clang engineers provide an even stricter -Weverything, which they insist is mostly for debugging the compiler. The Build Settings tab doesn’t expose those options, so put them in OTHER_CFLAGS if you need them.
EMBEDDED_CONTENT_CONTAINS_SWIFT—If your target uses Swift in its main code, the build system knows to include the Swift runtime libraries for compatibility with OS X 10.9 and iOS 7. The system will not detect Swift code in your plugins and helper apps for itself; if your app includes such, set this to YES to add the runtime to them as well.
Other Tools
As you saw in Chapter 25, “The Xcode Build System,” compilers aren’t the only build tools. Here are some settings for the others.
Asset Catalog Compiler
The images in an .xcassets catalog archive must be processed into more compact forms, and Info.plist must be patched to identify the application’s icons and launch images.
ASSETCATALOG_COMPILER_APPICON_NAME—The name of the image set containing the application’s icon.
(AppIcon)
ASSETCATALOG_COMPILER_LAUNCHIMAGE_NAME—The name of the image set for the launch image.
(LaunchImage)
COMPRESS_PNG_FILES—Whether to compress PNG image files before adding them to the product package.
(YES)
Info.plist
The Info.plist file in the project is just a source file for the Info.plist that will appear in the final package. The build process includes a step for resolving build-setting references, inserting mandatory keys, and, optionally, applying a C-style preprocessor.
INFOPLIST_FILE—The name of the file that will be the source for the bundle’s Info.plist file, if the product of this target is a bundle. This should not be Info.plist, as a project with more than one target will need to specify more than one Info.plist file.
(Info.plist)
If YES, INFOPLIST_PREPROCESS preprocesses the INFOPLIST_FILE, using a C-style preprocessor. You can specify a prefix file with INFOPLIST_PREFIX_HEADER and set symbols with INFOPLIST_PREPROCESSOR_DEFINITIONS.
(NO)
INFOPLIST_EXPAND_BUILD_SETTINGS—Controls whether build settings should be expanded in the generated Info.plist. This allows you, for instance, to fill the CFBundleExecutable key with ${EXECUTABLE_NAME }, and be assured that if you ever change the name of the product, Info.plist will always be in sync.
(YES)
INFOPLIST_OUTPUT_FORMAT—Your choice of the possible file formats for the Info.plist property-list file. This is binary if you want the binary format; anything else gets you an XML plist.
(binary)
INFOSTRINGS_PATH—The path, starting with the application package, to the InfoPlist.strings file for the development locale. The development locale is identified by DEVELOPMENT_LANGUAGE.
(Passer Rating.app/English.lproj/InfoPlist.strings)
CREATE_INFOPLIST_SECTION_IN_BINARY—Some single-file products, such as stand-alone libraries and command-line tools, must contain information for Launch Services and Finder. There can’t be a separate Info.plist file, so this option adds a Mach-O binary section for the Info.plist data.
(NO)
STRINGS_FILE_OUTPUT_ENCODING—.strings files map symbolic strings (usually English-language names) to strings that would be used for display in a particular language. (See Chapter 21, “Localization.”) This is the encoding for the processed string, historically UTF-16, but there is now a binary format that Cocoa can use more efficiently.
(binary)
Java
Apple abandoned Java as an OS X development language around 2002. (Java seemed like a good idea at the time; it always does.) There are a dozen Java-related settings still around, mostly with the prefix JAVA_. Xcode does not expose them. They don’t do anything. Ignore them.
Others
Some variables point to standard Unix tools. Development tools are usually found inside the Xcode.app package; others are simply the standard Unix commands to be found in the /bin, /usr/bin, /sbin, or /usr/sbin trees. Most Make-like systems factor tool names out this way, so switching to a custom tool is simply a matter of changing the single definitions.
The pointer variables (the tools they point to should be obvious to anyone who needs them) include CHOWN, CHMOD, CP, ICONV, LEX, SED, and YACC.
There are four commands of the form REMOVE_something_FROM_RESOURCES. These YES/NO switches determine whether version-control directories, and headers, should be ignored when copying files into the product bundle.
Search Paths
HEADER_SEARCH_PATHS—A space-delimited list of paths to directories the compiler is to search for headers, in addition to standard locations, such as /usr/include. If you add your own paths, carry the default paths through by putting $(inherited) at the beginning or end of your list. If the headers in question are in frameworks, set FRAMEWORK_SEARCH_PATHS instead. SDKROOT is prepended to the paths of system headers and frameworks.
(/Users/fritza/Library/... Build/Products/Debug-iphone-
simulator/include/Applications/Xcode.app/... /usr/include)
LIBRARY_SEARCH_PATHS—A space-delimited list of paths to directories the linker is to search for libraries. If set, SDKROOT is prepended to the paths of system libraries. Developers sometimes are given libraries in production and debug forms, as binaries, with no source; they’d like to use one version of the library in Debug builds and the other in Release builds. A solution is to put the two library versions in separate directories and specify different LIBRARY_SEARCH_PATHSes for the two build configurations.
(/Users/fritza/Library/... Build/Products/Debug-iphone-
simulator)
IPHONEOS_DEPLOYMENT_TARGET—The minimum version of iOS on which the product can run; symbols in the SDK from later versions of the OS are weak-linked. There is also a MACOSX_DEPLOYMENT_TARGET.
(8.2)
The DEVELOPER_ Variables
The settings that begin in DEVELOPER_ were a big part of the build environment in previous versions of Xcode, and the build system still sets them for the benefit of run-script build phases. They are read-only, so they appear nowhere in the default values in the Build Settings tab. Apple no longer documents them. I’m including them in case you have no alternative.
Many of the DEVELOPER_ paths had parallel SYSTEM_, SYSTEM_DEVELOPER_, PLATFORM_, and PLATFOTM_DEVELOPER_ settings, as the tool and frameworks sets may vary depending on whether you’re developing for OS X or iOS.
The only survivor is SYSTEM_LIBRARY_DIR, the root of the installation path for OS X frameworks.
If you’re looking for the paths to Xcode’s development tools, you’re better off using xcrun --find to pick out the ones that fit the current Xcode and any particular SDK you want. See man xcrun for more details.
DEVELOPER_DIR—The directory you chose for the Xcode installation. The DEVELOPER_ variables are important, because they track the currently selected Xcode if you have more than one installed. See man xcode-select.
(/Applications/Xcode.app/Contents/Developer)
DEVELOPER_APPLICATIONS_DIR—The folder inside DEVELOPER_DIR containing Xcode and the other developer applications. You may be better served by using open -a application-name if all you want to do is to launch a user application.
(/Applications/Xcode.app/Contents/Developer/Applications)
DEVELOPER_BIN_DIR—The folder inside DEVELOPER_DIR containing the BSD tools, like clang, that Xcode uses. If you write scripts that execute development tools like clang or yacc directly, use this path instead of /usr/bin. The tools in this directory are the versions that correspond to the version of Xcode you’re using.
(/Applications/Xcode.app/Contents/Developer/usr/bin)
DEVELOPER_FRAMEWORKS_DIR—The folder inside DEVELOPER_DIR that contains development frameworks, such as for unit tests. There’s also a QUOTED variant that you can use with the confidence that a shell interpreter won’t mangle it.
(/Applications/Xcode.app/Contents/Developer/Library/Frameworks)
DEVELOPER_LIBRARY_DIR—The folder inside DEVELOPER_DIR containing files (templates, plugins, etc.) that support the developer tools.
(/Applications/Xcode.app/Contents/Developer/Library)
DEVELOPER_SDK_DIR—The folder inside DEVELOPER_DIR that contains the software development kit for the platform the target will run on. (Simulator targets run on OS X.)
(/Applications/Xcode.app/Contents/Developer/Platforms
/MacOSX.platform/Developer/SDKs)
DEVELOPER_TOOLS_DIR—Contains BSD tools, like SetFile, that are specific to OS X development and would not be expected to be in /usr/bin.
(/Applications/Xcode.app/Contents/Developer/Tools)
DEVELOPER_USR_DIR—The folder inside DEVELOPER_DIR that you should use as a prefix for the standard include, sbin, share, and other directories you’d ordinarily look for in the root /usr directory.
(/Applications/Xcode.app/Contents/Developer/usr)
Source Trees
A source tree provides a particular kind of build variable, a path to a directory or to the root directory of a tree with a known structure. The path can be a location to receive build results or provide access to a system of libraries and headers. When used to build source paths, a source tree provides a reliable shorthand for packages that do not belong in the directory tree of any one project.
For example, I use the eSellerate libraries in my OS X projects. I define a source tree for the eSellerate libraries by opening the Preferences window, selecting the Source Trees tab of the Locations panel, and clicking the + button to add an entry. I choose ESELLERATE_DIR for the setting name and eSellerate Directory for the display name, and I type the full path name for the root of the eSellerate SDK into the path column.
Now, when I add a file reference to my project, I can use the File inspector in the Utility area to set Location to Relative to eSellerate Directory. Regardless of who copies or clones my project, so long as they have defined an ESELLERATE_DIR source tree, the project will find that file in their copy of that directory. I don’t have to care about the details of the path, and I especially don’t have to set up double-dot relative directory references.
Source trees are global—they span projects—but are per-user.