 |
|
|
|
|
|
||
 |
|
||
|
|
||
|
||||||||||||||
|
| < Previous PageNext Page > |
In Mac OS X, there are two basic ways to organize information inside of a bundle. The first way is to create a “modern” bundle. Modern bundles reflect a structure that is different from the bundle organization that came before Mac OS X. This bundle style is used by applications and plug-ins and are the most common type of bundle. The second type of bundle, the “versioned” bundle, is most often used by frameworks, which may have multiple revisions of the same information.
Bundles have evolved significantly over the years but the overall goal has been the same. The bundle organization makes it easier for the application to find its resources while making it harder for users to interfere with those resources. Because the Finder treats most bundles as opaque entities, it is difficult for casual users to move or delete the resources an application might need.
Everything an application requires should be stored inside its bundle directory. This includes the following types of resources:
The sections that follow introduce you to the basics of bundle organization and show you how to extend that organization in ways that take advantage of Mac OS X.
Modern Bundle Structure
Framework Bundle Structure
The basic structure of a modern bundle is very simple. At
the top-level of the bundle is a folder named Contents.
This directory contains everything, including resources, executable
code, private frameworks, private plug-ins, and support files needed
by the application or plug-in. While the Contents folder
might seem superfluous, it identifies the bundle as a modern-style
bundle and separates it from document and legacy bundle types.
Inside the Contents folder,
you can add numerous other files to implement your bundle. The following
sections explain the types of files you can add. These sections
are cumulative, that is, each section builds on the contents of
the previous section to show you how to build a more full-featured
bundle in stages.
For the Finder to recognize an executable bundle as such,
there is only one file you need to have in your bundle, and that
is an Info.plist file.
This file is an XML property-list file that contains information
about your bundle’s configuration. 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, such as the following:
The exact information you put into your Info.plist file
is dependent on your application’s needs and can be localized
as necessary. For more information on this file, see the Runtime Configuration programming
topic.
The most important thing to add to your executable bundle
is your executable binary. This is the file compiled from your source
code and linked into a form that can be executed on the target computer.
Binaries that run natively in Mac OS X go in a MacOS directory
inside the Contents folder.
If your application runs only the Classic compatibility environment, you
should put your legacy executable into a MacOSClassic directory
instead.
Listing 4-1 shows a bundle that whose main executable runs natively in Mac OS X but that uses a helper tool that runs only in the Classic compatibility environment.
|
You may notice in the preceding listing that the bundle also
includes an alias to the main executable at the same level as the Contents folder.
When the user launches your application from the Dock or Finder,
Launch Services uses this alias to run your main executable. If
there are any other executables in your bundle, your main executable
must launch them.
Resources in your bundle belong in a separate Resources directory
just inside the Contents folder.
This is where you put image, sound, nib, strings, and icon files
among others. The top-level Resources directory
contains resources that apply to all localized versions of your application.
If you have locale-specific resources, you should put them into language-specific
subdirectories, described in “Adding Localized Resources”.
Listing 4-2 shows a bundle that includes some resources in the native language of the program.
One special resource that belongs in your top-level 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.
Within the Resources directory,
you can create one or more additional subdirectories to store locale-specific
resources. The name of each directory is based on the language and region
of the translation followed by the .lproj extension.
For all languages, you can use either the ISO 639 or ISO 3166 standards
for specifying language directories. The ISO 3166 format is as follows:
language_region.lproj
In this format, both the language and region designators are
two-letter ISO codes. If you are not localizing for specific regions,
you may omit the region portion and use just the ISO 639 language
code. For example, you could specify English resources in an en.lproj directory
or you could specifically localize your English resources for the
United States region by putting them in a en_US.lproj directory.
The NSBundle and CFBundle mechanisms also support human-readable
names for several common languages.
Each of your localized resource directories should contain a copy of the same resource files. The names of the files must all be the same; only the content of the files differs based on the localization. When your application asks for a resource file, Mac OS X uses the current language preferences to return the file from the appropriate localization directory.
Listing 4-3 shows a bundle that includes localized resources for multiple foreign languages.
|
For more information about internationalization and localization, see the Internationalizing Your Software programming topic.
While executable and resource files are standard in most bundles, there are several other special directories that are not needed by most bundles. These directories include the following:
Frameworks directory
contains any private frameworks used by the executable. PlugIns directory
contains any bundles that the current bundle can load dynamically. These
bundles extend the basic features of the executable.SharedSupport directory
contains additional non-critical resources that do not impact the
ability of the application to run. For example, this directory might
include things like document templates, clip art, and tutorials. All of these directories in are inextricably bound to the application. This is particularly true for frameworks. The dynamic shared libraries of embedded frameworks are revision-locked and cannot be superseded by any other, even newer, versions that may be available to the operating system.
Listing 4-1 shows the bundle structure for a fully-localized application that supports these directories.
|
Framework bundles use different bundle structure than current modern bundles. This structure is based on an older bundle format and allows for multiple versions of the framework code and header files to be stored inside the bundle. Supporting multiple versions allows older applications to continue running even as the framework binary continues to evolve.
The system identifies frameworks by looking for a Resources directory
at the top-level of the bundle. Inside this directory is an Info.plist file
that contains the bundle identifying information. Your actual Resources directory
does not have to reside physically at the top-level of your bundle.
In fact, the system frameworks that come with Mac OS X put an alias
in this location. The alias itself points to the most current version
of the Resources directory,
buried somewhere deep inside the bundle.
When you build a new framework project in Xcode, the build environment creates a versioned bundle structure for you automatically. Listing 4-5 shows you the basic structure of the resulting bundle:
|
In this listing, the top-level references to MyFramework and Resources are
both aliases to the items in folder A.
That is because A contains
the actual contents of the framework. It contains both the executable
and the resources used by the framework.
The Current item
inside the Versions folder
is actually an alias that points to the most recent revision of
the framework. So, if you had a framework with multiple revisions,
as shown in Listing 4-6, the Current alias
would point to most recent revision, folder B.
in this case. Similarly, the top-level aliases would point to the
respective resources inside folder B.
|
Frameworks typically include more directories than just a Resources directory.
When you install the Developer Tools packages on your system, the
installer installs any included header files for the framework.
As with all framework resources, any additional directories you
install go inside a specific version of the framework, with an alias
to the current version at the top-level of the framework. Thus,
adding a Headers directory
to the example in Listing 4-6 would result in a framework like the one shown in Listing 4-7.
|
Frameworks require the same sort of configuration as any other type of bundle. In the information property list for your framework, make sure you include the following information:
'FMWK')Because frameworks are never associated with documents directly, you should never specify any document types. You may include display name information if you wish.
For more information on configuration and information property lists, see the Runtime Configuration programming topic.
| < Previous PageNext Page > |
Last updated: 2003-08-21
|
|
|
| ||
| ||
Get information on Apple products.
Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2003 Apple Computer, Inc. All rights reserved. | Terms of use | Privacy Notice |