1.1. Anatomy of an Application

Apple came up with an elegant way to contain applications in their operating system. As OS X is a Unix-based platform, Apple wanted to make it adhere to basic Unix file conventions, and so the resource forks of olde were no longer sufficient (or efficient, for that matter). The challenge was to design a structure that would allow an application to remain self-contained while surviving on a file system that didn't believe in cheapening its architecture with proprietary workarounds. The answer came from an older ancestor of Mac OS X named NeXT, which treated an application as a bundle represented within a directory. The bundle concept introduces an approach to group application resources, binaries, and other related files.

If you look at any Mac application, you'll find that the .app extension denotes not a file, but a directory. This is the application's program directory. Inside it is an organized structure containing resources the application needs to run, property lists containing information about the application, and the application's executable binaries. The iPhone SDK builds the binary executable for your program and deposits files it needs into this program directory structure. So to build a complete application, it's up to the developer to tell the Xcode IDE which supporting files should be installed. Applications are executed from within a sandbox on the iPhone. A sandbox is a restricted environment that prevents applications from accessing unauthorized resources. One of its functions is to prohibit any read or write operations outside of the application's designated home directory. Everything your application needs to run must be self-contained within this directory structure. In addition to this, your application won't know where it is installed, as a unique identifier is added to your application's path at each installation. You'll only be able to find your path by using functions like NSHomeDirectory and classes like NSBundle, which you'll learn about in the coming chapters.

Each iPhone application has its own home directory containing Library and Documents folders, and a tmp directory for storing temporary files. The program directory for an iPhone application is much less structured than desktop Mac applications, and all of the application's resources are stored in the root of the .app program folder. The following is an example of a single application's complete home directory, as it might appear on the iPhone's file system:

drwxr-xr-x    mobile  mobile   Documents/
drwxr-xr-x    mobile  mobile   Library/
drwxr-xr-x        mobile  mobile    Preferences/
drwxr-xr-x    mobile  mobile   MyApp.app/
    drw-r--r--    mobile  mobile    _CodeSignature
    -rw-r--r--    mobile  mobile    Default.png
    -rw-r--r--    mobile  mobile    icon.png
    -rw-r--r--    mobile  mobile    Info.plist
    -rwxr-xr-x    mobile  mobile    MyApp
    -rw-r--r--    mobile  mobile    pie.png
    -rw-r--r--    mobile  mobile    PkgInfo
    -rw-r--r--    mobile  mobile    ResourceRules.plist
drwxr-xr-x    mobile  mobile   tmp/

This list reflects a very basic simple iPhone application named MyApp:



Documents

A special folder in which your application may store documents created by the user. It will not be shared with any other applications' documents.



Library

A folder in which your application may store settings and other resources created after installation. Inside this folder is another folder named Preferences, which will store your application's preferences. You'll learn how to access them in Chapter 11.



MyApp.app

The application folder, this represents the actual application. This directory will contain your executable binary and all supporting resources your application relies on.



_CodeSignature

A directory containing code signatures for each file bundled with your application. These ensure that the application has not been modified from its original form. All applications must be signed in order to run on the iPhone.



Default.png

A PNG (portable network graphics) image file containing the application's default title screen. When the user runs your application, the iPhone animates it to give the appearance that it's zooming to the front of the screen. The application's Default.png file is loaded and scaled up until it fills the entire screen. This 320x480 image zooms to the front and remains on the screen until the application finishes launching. Applications generally use a solid black or white background, a logo, or a background resembling the title screen that an application will display after initializing.



icon.png

A PNG image containing the application's icon. The icon is displayed on the iPhone's home screen. Apple recommends that icons be 57x57 pixels. This file can be named anything you like, as long as it's specified in the Info.plist manifest, explained below. Icons are automatically given a "shine" when displayed, so you won't need to worry about drawing rounded edges or lighting effects on your icon.



Info.plist

A property list containing information about the application. This includes the name of its binary executable and a bundle identifier, which is read when the application is launched. You'll see an example property list later in this chapter.



MyApp

The actual binary executable that is called when the application is launched. This is what Xcode outputs when it builds your application. Xcode will automatically place the binary in the application folder when performing a Build and Go.



pie.png

An example image resource used by this sample application. The iPhone framework provides many methods to fetch resources, so you don't need to access them directly by path. This is consistent with Apple's effort to keep applications self-contained. The Xcode IDE will take any files you've dragged into your project's Resources folder (on the desktop) and will place them into the application's program folder (on the iPhone) when the project is installed.



PkgInfo

This file contains the eight-byte filetype descriptor for the application. The first four bytes should read APPL, followed by the bundle signature identifier. This is explained in the next section.

1.1.1. Underneath Xcode

Before delving into the many great benefits provided to you by Xcode, it would be healthy to understand the basics of how an application is assembled. In the old world of iPhone hacking, this meant rolling your own application by hand. In Xcode, this is done for you. Here's what's going on behind the scenes.

If you were building an application by hand, you'd put together a skeleton .app directory to contain it. The skeleton provides all of the information necessary for the iPhone to acknowledge the existence of your application as a bundle so it can be run from the iPhone's home screen.

This book presents many fully functional code examples whose skeleton is built automatically by Xcode. After compiling the example, Xcode creates the example's directory structure inside the project's build directory and places its binary and resources into the application folder. If you were doing this by hand, creating the directory would be easy enough:

$ mkdir MyExample.app

Next, Xcode copies a property list into the application folder to describe the application and how to launch it. The Info.plist file expresses this information in XML format and looks like this:

<?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>CFBundleDevelopmentRegion</key>
        <string>en</string>
        <key>CFBundleDisplayName</key>
        <string>${PRODUCT_NAME}</string>
        <key>CFBundleExecutable</key>
        <string>${EXECUTABLE_NAME}</string>
        <key>CFBundleIconFile</key>
        <string>icon.png</string>
        <key>CFBundleIdentifier</key>
        <string>com.yourcompany.${PRODUCT_NAME:identifier}</string>
        <key>CFBundleInfoDictionaryVersion</key>
        <string>6.0</string>
        <key>CFBundleName</key>
        <string>${PRODUCT_NAME}</string>
        <key>CFBundlePackageType</key>
        <string>APPL</string>
        <key>CFBundleResourceSpecification</key>
        <string>ResourceRules.plist</string>
        <key>CFBundleSignature</key>
        <string>????</string>
        <key>CFBundleVersion</key>
        <string>1.0</string>
        <key>LSRequiresIPhoneOS</key>
        <true/>
</dict>
</plist>

                                          

The most important keys are CFBundleDisplayName, CFBundleExecutable, CFBundleIconFile, CFBundleIdentifier, and CFBundleName. The CFBundleExecutable property is of particular importance, as it specifies the filename of the binary executable within the folder. This is the file that is executed when your application is launched—the output from your compiler. Xcode normally sets this automatically, but you can override this behavior.

The iPhone's home screen runs as an application, called Springboard, which is similar to the Finder on a Mac desktop. The Springboard application, as well as much of the iPhone's application layer, likes to refer to applications using a special identifier instead of its display name; for example com.yourcompany.tictactoe. The value assigned to the CFBundleIdentifier key specifies the unique identifier you'd like to give to your application. Whenever your application is launched, it will be referenced using this identifier. Because the name must be unique among all other applications on the iPhone, it's common practice to incorporate the URL of your website.

The application's icon.png and Default.png files are also copied into the program folder, if they exist. If you leave these out, the iPhone will use the worst-looking images possible to serve as default images for both. Make sure to create and include images with these names when you publish your own applications to make them look professional.

Were this application signed by Xcode, it would be good enough to run. In the next section, you'll install the iPhone SDK on your desktop, which will perform all of these steps for you when you build an application—and sign the build with your developer key.

You'll get started compiling example applications as early as Chapter 3. In the coming chapters, you'll build many examples. The examples provided in this book generally do not need any additional resources, however a few will use your Internet connection to download sample images or other files.

NOTE

 

You can download the code examples in this book from the book's online repository at http://www.oreilly.com/catalog/9780596154059.