Xcode Build Tokens

2 minute read

Recently, I was working with a larger iOS project than I usually do. This project involved creating a library and using it in other applications as well as testing it. In order to make this as painless as possible I started using bash script to make my builds as efficient as possible. In doing this I discovered many many Xcode build tokens which are underused. Lots of these made my build scripts a lot easier to create as I didn’t need to work with lots of relative paths, and helped ignore lots of redundant builds and build steps.

One of the biggest issues that I had with these tokens was the lack of documentation by Apple on these. A good chunk of these are based on my observations of how they change with various project settings. Some of them may not be quite right and if that is the case, feel free to let me know on this one and I’ll be glad to update it. I’m taking the unusual step on this post and adding in a comment system to see how well received this is (as well as test the suitablity of a comment system for this site), so please let me know through there.

Anyway, here are some of the more useful tokens that I found:

  • BUILD_DIR: The location of the build directory. This is normally somewhere deep in the derived data folder, but can be configured in Xcode.
    • /some/project/path/build/build
  • BUILD_ROOT: This doesn't seem to be mentioned anywhere in Apple's documentation(just like lots of flags here), but seems to be set to the same thing as BUILD_DIR.
    • /some/project/path/build/build
  • BUILT_PRODUCTS_DIR: The location where the final products are placed after building.
    • /some/project/path/build/build/Debug-iphoneos
  • COMPRESS_PNG_FILES: A boolean value which specifies whether to compress PNG files whenthey are copied into the application bundle on iOS.
    • YES
  • CONFIGURATION: The current build configuration. This is usually Debug or Release,but can be a custom configuration.
    • Debug
  • CONFIGURATION_BUILD_DIR: The build directory for the current configuration. This seems togenerally be the same as the BUILD_PRODUCTS_DIR.
    • /some/project/path/build/build/Debug-iphoneos
  • CURRENT_ARCH: Identifies the architecture on which the build is being *performed*.
    • i386
  • DEBUGGING_SYMBOLS: A boolean which specifies if debug symbols should be included in thecurrent build.
    • YES
  • DEVELOPMENT_LANGUAGE: Specifies the language that the project was developed in. Note thatthis means English/Spanish/etc. and *not* Objective-C/C++/etc.
    • English
  • EFFECTIVE_PLATFORM_NAME: The platform which the build is being performed for, prefixed with a- usually. This can be combined with CONFIGURATION to get builddirectories usually.
    • -iphoneos
  • INSTALL_OWNER: The user who owns the final built product. This can be used to getappropriate permissions, etc.
    • SomeUser
  • IPHONEOS_DEPLOYMENT_TARGET: This one is simply the iOS deployment target. If you are developingfor iOS 7.0 then set it to 7.0.
    • 7.0
  • ONLY_ACTIVE_ARCH: A boolean flag which states if the build will be performed for theactive architecture only.
    • YES
  • OPTIMIZATION_LEVEL: The optimisation level which is used by GCC compatible compilers.
    • 0
  • PATH: The PATH variable which is the same as you would see in a regularBash environment.
    • "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/usr/local/bin:/usr/bin:/bin:/usr/sbin"
  • PLATFORM_NAME: The name of the current platform. This time there is no - unlike theEFFECTIVE_PLATFORM_NAME.
    • iphoneos
  • PRODUCT_NAME: The current products name. This is usually the same name as the currentbuild target.
    • "Universal Build"
  • PROJECT: The name of the project.
    • SuperAwesomeProject
  • PROJECT_DIR: The location of the .xcodeproj directory.
    • /some/project/path/
  • PROJECT_FILE_PATH: Similar to PROJECT_DIR, but this one places the .xcodeproj directoryon the end.
    • /some/project/path/build/Redstone_Common.xcodeproj
  • PROJECT_NAME: Seems to be identical to PROJECT.
    • SuperAwesomeProject
  • SDK_NAME: The current SDK being used.
    • iphoneos7.1
  • SOURCE_ROOT: The location of the source code for this project.
    • /some/project/path
  • SRCROOT: An alias for SOURCE_ROOT
    • /some/project/path
  • TARGETNAME: The name of the current target.
    • "Universal Build"
  • TARGET_BUILD_DIR: The build directory of the current target.
    • /some/project/path/build/build/Debug-iphoneos
  • TARGET_NAME: An alias for TARGETNAME.
    • "Universal Build"
  • USER: The current system user.
    • SomeUser