File | Description |
---|---|
Info.plist file | (Required) The information property list file is a structured file that contains configuration information for the application. The system relies on the presence of this file to identify relevant information about your application and any related files. |
Executable | (Required) Every application must have an executable file. This file contains the application’s main entry point and any code that was statically linked to the application target. |
Resource files | Resources are data files that live outside your application’s executable file. Resources typically consist of things like images, icons, sounds, nib files, strings files, configuration files, and data files (among others). Most resource files can be localized for a particular language or region or shared by all localizations. The placement of resource files in the bundle directory structure depends on whether you are developing an iOS or Mac app. |
Other support files | Mac apps can embed additional high-level resources such as private frameworks, plug-ins, document templates, and other custom data resources that are integral to the application. Although you can include custom data resources in your iOS application bundles, you cannot include custom frameworks or plug-ins. |
MyApp
. The only files that are required to be in subdirectories are those that need to be localized; however, you could create additional subdirectories in your own applications to organize resources and other relevant files. File | Description |
---|---|
MyApp | (Required) The executable file containing your application’s code. The name of this file is the same as your application name minus the .app extension. |
Application icons ( MyAppIcon.png , MySearchIcon.png , and MySettingsIcon.png ) | (Required/Recommended) Application icons are used at specific times to represent the application. For example, different sizes of the application icon are displayed in the Home screen, in search results, and in the Settings application. Not all of the icons are required but most are recommended. For information about application icons, see Application Icon and Launch Images. |
Info.plist | (Required) This file contains configuration information for the application, such as its bundle ID, version number, and display name. See The Information Property List File for further information. |
Launch images ( Default.png ) | (Recommended) One or more images that show the initial interface of your application in a specific orientation. The system uses one of the provided launch images as a temporary background until your application loads its window and user interface. If your application does not provide any launch images, a black background is displayed while the application launches. For information about application icons, see Application Icon and Launch Images. |
MainWindow.nib | (Recommended) The application’s main nib file contains the default interface objects to load at application launch time. Typically, this nib file contains the application’s main window object and an instance of the application delegate object. Other interface objects are then either loaded from additional nib files or created programmatically by the application. (The name of the main nib file can be changed by assigning a different value to the NSMainNibFile key in the Info.plist file. See The Information Property List File for further information.) |
Settings.bundle | The Settings bundle is a special type of plug-in that contains any application-specific preferences that you want to add to the Settings application. This bundle contains property lists and other resource files to configure and display your preferences. |
Custom resource files | Non-localized resources are placed at the top level directory and localized resources are placed in language-specific subdirectories of the application bundle. Resources consist of nib files, images, sound files, configuration files, strings files, and any other custom data files you need for your application. For more information about resources, see Resources in an iOS Application. |
.lproj
folder for each language it supports. In addition to providing localized versions of your application’s custom resources, you can also localize your launch images by placing files with the same name in your language-specific project directories. Even if you provide localized versions, however, you should always include a default version of these files at the top-level of your application bundle. The default version is used in situations where a specific localization is not available. For more information about localized resources, see Localized Resources in Bundles. Info.plist
) file containing the application’s configuration information. When you create a new iOS application project, Xcode creates this file automatically and sets the value of some of the key properties for you. Table 2-3 lists some additional keys that you should set explicitly. (Xcode obscures actual key names by default, so the string displayed by Xcode is also listed in parenthesis where one is used. You can see the real key names for all keys by Control-clicking the Information Property List key in the editor and choosing Show Raw Keys/Values from the contextual menu that appears.) Key | Value |
---|---|
CFBundleDisplayName (Bundle display name) | The bundle display name is the name displayed underneath the application icon. This value should be localized for all supported languages. |
CFBundleIdentifier (Bundle identifier) | The bundle identifier string identifies your application to the system. This string must be a uniform type identifier (UTI) that contains only alphanumeric ( A -Z ,a -z ,0 -9 ), hyphen (- ), and period (. ) characters. The string should also be in reverse-DNS format. For example, if your company’s domain is Ajax.com and you create an application named Hello, you could assign the string com.Ajax.Hello as your application’s bundle identifier. The bundle identifier is used in validating the application signature. |
CFBundleVersion (Bundle version) | The bundle version string specifies the build version number of the bundle. This value is a monotonically increased string, comprised of one or more period-separated integers. This value cannot be localized. |
CFBundleIconFiles | An array of strings containing the filenames of the images used for the application’s assorted icons. Although technically not required, it is strongly encouraged that you use it. This key is supported in iOS 3.2 and later. |
LSRequiresIPhoneOS (Application requires iOS environment) | A Boolean value that indicates whether the bundle can run on iOS only. Xcode adds this key automatically and sets its value to true. You should not change the value of this key. |
UIRequiredDeviceCapabilities | A key that tells iTunes and the App Store know which device-related features an application requires in order to run. iTunes and the mobile App Store use this list to prevent customers from installing applications on a device that does not support the listed capabilities. The value of this key is either an array or a dictionary. If you use an array, the presence of a given key indicates the corresponding feature is required. If you use a dictionary, you must specify a Boolean value for each key indicating whether the feature is required. In both cases, not including a key indicates that the feature is not required. For a list of keys to include in the dictionary, see Information Property List Key Reference. This key is supported in iOS 3.0 and later. |
Para | Para |
---|---|
NSMainNibFile (Main nib file base name) | A string that identifies the name of the application’s main nib file. If you want to use a nib file other than the default one created for your project, associate the name of that nib file with this key. The name of the nib file should not include the .nib filename extension. |
UIStatusBarStyle | A string that identifies the style of the status bar as the application launches. This value is based on the UIStatusBarStyle constants declared in UIApplication.h header file. The default style is UIStatusBarStyleDefault . The application can change this initial status-bar style when it finishes launching.If you do not specify this key, iOS displays the default status bar. |
UIStatusBarHidden | A Boolean value that determines whether the status bar is initially hidden when the application launches. Set it to true to hide the status bar. The default value is false . |
UIInterfaceOrientation | A string that identifies the initial orientation of the application’s user interface. This value is based on the UIInterfaceOrientation constants declared in the UIApplication.h header file. The default style is UIInterfaceOrientationPortrait . |
UIPrerenderedIcon | A Boolean value that indicates whether the application icon already includes gloss and bevel effects. The default value is false . Set it to true if you do not want the system to add these effects to your artwork. |
UIRequiresPersistentWiFi | A Boolean value that notifies the system that the application uses the Wi-Fi network for communication. Applications that use Wi-Fi for any period of time must set this key to true ; otherwise, after 30 minutes, the device shuts down Wi-Fi connections to save power. Setting this flag also lets the system know that it should display the network selection dialog when Wi-Fi is available but not currently being used. The default value is false . Even if the value of this property is true , this key has no effect when the device is idle (that is, screen-locked). During that time, the application is considered inactive and, although it may function on some levels, it has no Wi-Fi connection. |
UILaunchImageFile | A String containing the base filename used by the application’s launch images. If you do not specify this key, the base name is assumed to be the string Default . |
CFBundleIconFiles
key. For detailed information about how to specify the icons and launch images in your application, see the discussion of these items in Advanced App Tricks in App Programming Guide for iOS. Info.plist
file. Most iOS applications have at least a few files at this level, including the application’s icon, launch image, and one or more nib files. Although you should place most nonlocalized resources in this top-level directory, you can also create subdirectories to organize your resource files. Localized resources must be placed in one or more language-specific subdirectories, which are discussed in more detail in Localized Resources in Bundles. Hand.png
, MainWindow.nib
, MyAppViewController.nib
, and the contents of the WaterSounds
directory. The localized resources include everything in the en.lproj
and jp.lproj
directories. Contents
. This directory contains everything, including the resources, executable code, private frameworks, private plug-ins, and support files needed by the application. While the Contents
directory might seem superfluous, it identifies the bundle as a modern-style bundle and separates it from document and legacy bundle types found in earlier versions of Mac OS. Contents
directory. This structure represents the core of every Mac app. Contents
directory, along with the purpose of each one. This list is not exhaustive but merely represents the directories in common usage.Directory | Description |
---|---|
MacOS | (Required) Contains the application’s standalone executable code. Typically, this directory contains only one binary file with your application’s main entry point and statically linked code. However, you may put other standalone executables (such as command-line tools) in this directory as well. |
Resources | Contains all of the application’s resource files. This contents of this directory are further organized to distinguish between localized and nonlocalized resources. For more information about the structure of this directory, see The Resources Directory |
Frameworks | Contains any private shared libraries and frameworks used by the executable. The frameworks in this directory are revision-locked to the application and cannot be superseded by any other, even newer, versions that may be available to the operating system. In other words, the frameworks included in this directory take precedence over any other similarly named frameworks found in other parts of the operating system. For information on how to add private frameworks to your application bundle, see Framework Programming Guide. |
PlugIns | Contains loadable bundles that extend the basic features of your application. You use this directory to include code modules that must be loaded into your application’s process space in order to be used. You would not use this directory to store standalone executables. |
SharedSupport | Contains additional non-critical resources that do not impact the ability of the application to run. You might use this directory to include things like document templates, clip art, and tutorials that your application expects to be present but that do not affect the ability of your application to run. |
Info.plist
) file. This file contains XML property-list data that identifies the configuration of your bundle. For a minimal bundle, this file would contain very little information, most likely just the name and identifier of the bundle. For more complex bundles, the Info.plist
file includes much more information. Info.plist
file. Xcode provides all of these keys automatically when you create a new project. (Xcode obscures actual key names by default, so the string displayed by Xcode is also listed in parenthesis. You can see the real key names for all keys by Control-clicking the Information Property List key in the editor and choosing Show Raw Keys/Values from the contextual menu that appears.) Key | Description |
---|---|
CFBundleName (Bundle name) | The short name for the bundle. The value for this key is usually the name of your application. Xcode sets the value of this key by default when you create a new project. |
CFBundleDisplayName (Bundle display name) | The localized version of your application name. You typically include a localized value for this key in an InfoPlist.strings files in each of your language-specific resource directories. |
CFBundleIdentifier (Bundle identifier) | The string that identifies your application to the system. This string must be a uniform type identifier (UTI) that contains only alphanumeric ( A -Z ,a -z ,0 -9 ), hyphen (- ), and period (. ) characters. The string should also be in reverse-DNS format. For example, if your company’s domain is Ajax.com and you create an application named Hello, you could assign the string com.Ajax.Hello as your application’s bundle identifier. The bundle identifier is used in validating the application signature. |
CFBundleVersion (Bundle version) | The string that specifies the build version number of the bundle. This value is a monotonically increased string, comprised of one or more period-separated integers. This value can correspond to either released or unreleased versions of the application. This value cannot be localized. |
CFBundlePackageType (Bundle OS Type code) | The type of bundle this is. For applications, the value of this key is always the four-character string APPL . |
CFBundleSignature (Bundle creator OS Type code) | The creator code for the bundle. This is a four-character string that is specific to the bundle. For example, the signature for the TextEdit application is ttxt . |
CFBundleExecutable (Executable file) | The name of the main executable file. This is the code that is executed when the user launches your application. Xcode typically sets the value of this key automatically at build time. |
Info.plist
file. Key | Description |
---|---|
CFBundleDocumentTypes (Document types) | The document types supported by the application. This type consists of an array of dictionaries, each of which provides information about a specific document type. |
CFBundleShortVersionString (Bundle versions string, short) | The release version of the application. The value of this key is a string comprised of three period-separated integers. |
LSMinimumSystemVersion (Minimum system version) | The minimum version of macOS required for this application to run. The value for this key is a string of the form n.n.n where each n is a number representing either the major or minor version number of macOS that is required. For example, the value 10.1.5 would represent macOS v10.1.5. |
NSHumanReadableCopyright (Copyright (human-readable)) | The copyright notice for the application. This is a human readable string and can be localized by including the key in an InfoPlist.strings file in your language-specific project directories. |
NSMainNibFile (Main nib file base name) | The nib file to load when the application is launched (without the .nib filename extension). The main nib file is an Interface Builder archive containing the objects (main window, application delegate, and so on) needed at launch time. |
NSPrincipalClass (Principal class) | The entry point for dynamically loaded Objective-C code. For an application bundle, this is almost always the NSApplication class or a custom subclass. |
Info.plist
file is dependent on your bundle’s needs and can be localized as necessary. For more information on this file, see Runtime Configuration Guidelines. Resources
directory is where you put all of your images, sounds, nib files, string resources, icon files, data files, and configuration files among others. The contents of this directory are further subdivided into areas where you can store localized and nonlocalized resource files. Non-localized resources reside at the top level of the Resources
directory itself or in a custom subdirectory that you define. Localized resources reside in separate subdirectories called language-specific project directories, which are named to coincide with the specific localization.Resources
directory is organized is to look at an example. Listing 2-4 shows a fictional application that includes both localized and nonlocalized resources. The nonlocalized resources include Hand.tiff
, MyApp.icns
and the contents of the WaterSounds
directory. The localized resources include everything in the en.lproj
and jp.lproj
directories or their subdirectories. Resources
directory is your application icon file. By convention, this file takes the name of the bundle and an extension of .icns
; the image format can be any supported type, but if no extension is specified, the system assumes .icns
.Info.plist
file contain user-visible strings, macOS provides a mechanism for specifying localized versions of those strings. Inside each language-specific project directory, you can include an InfoPlist.strings
file that specifies the appropriate localizations. This file is a strings file (not a property list) whose entries consist of the Info.plist
key you want to localize and the appropriate translation. For example, in the TextEdit application, the German localization of this file contains the following strings:Info.plist
file and typically several other files to help you get started quickly. You can add any custom files as needed using the project window and configure those files using the Info or Inspector windows. For example, you might use the Info window to specify custom locations for resource files inside your bundle. /System/Library/Frameworks
directory. In iOS, the public frameworks are located in the System/Library/Frameworks
directory of the appropriate iOS SDK directory. For information about adding frameworks to your Xcode projects, see Xcode Build System Guide. Versions
subdirectory contains the individual framework revisions while symbolic links at the top of the bundle directory point to the latest revision..framework
extension on its directory name. The system also uses the Info.plist
file inside the framework’s Resources
directory to gather information about the configuration of the framework. Listing 2-5 shows the basic structure of a framework bundle. The arrows (->
) in the listing indicate symbolic links to specific files and subdirectories. These symbolic links provide convenient access to the latest version of the framework. Headers
directory but doing so allows you to include the header files that define the framework’s exported symbols. Frameworks can store other resource files in both standard and custom directories. Contents
directory. Inside this directory are several subdirectories for storing executable code and resources. The Contents
directory also contains the bundle’s Info.plist
file with information about the bundle’s configuration. main
function as their main entry point. Instead, the application that loads the bundle is responsible for defining the expected entry point. For example, a bundle could be expected to define a function with a specific name or it could be expected to include information in its Info.plist
file identifying a specific function or class to use. This choice is left to the application developer who defines the format of the loadable bundle..bundle
and .plugin
. macOS always treats bundles with those extensions as packages, hiding their contents by default. MacOS
and Resources
directories, loadable bundles may contain additional directories such as Frameworks
, PlugIns
, SharedFrameworks
, and SharedSupport
—all the features supported by full-fledged application packages. Resources
directory of a macOS bundle (or the top-level directory of an iOS application bundle), you can create one or more language-specific project subdirectories to store language- and region-specific resources. The name of each directory is based on the language and region of the desired localization followed by the .lproj
extension. To specify the language and region, you use the following format: _
region.lproj
en.lproj
directory to support all English speaking nations. However, providing separate localizations for Great Britain (en_GB.lproj
), Australia (en_AU.lproj
), and the United States (en_US.lproj
) lets you tailor your content for each of those countries. NSBundle
class and CFBundleRef
functions also support human-readable directory names for several common languages, including English.lproj
, German.lproj
, Japanese.lproj
, and others. Although the human-readable names are supported, the ISO names are preferred.lproj
folders, because the system does not load or execute code stored in lproj
folders. To learn more about where code and other types of data should be stored in your app bundle, see macOS Code Signing In Depth.Resources
directory would be at the top-level of the bundle directory.) Notice that the region-specific directories contain only a subset of the files in the en.lproj
directory. If a region-specific version of a resource is not found, the bundle looks in the language-specific directory (in this case en.lproj
) for the resource. The language-specific directory should always contain a complete copy of any language-specific resource files.