Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.

NSBundle

Inherits From: NSObject

Conforms To: NSObject (NSObject)

Declared In: Foundation/NSBundle.h

Class Description

A bundle is a mechanism for grouping application resources into convenient chunks. A typical (but by no means the only) application of a bundle is to group executable code together with the resources used by that executable code. A major use of bundles is to handle localization issues, as described below in Localized Resources.

An NSBundle is an object that corresponds to a directory (or folder in the terminology of some operating systems) where application resources are stored. The directory, in essence, bundles a set of resources used by an application, and the NSBundle object makes those resources available to the application. NSBundle is able to find requested resources in the directory and, in some cases, dynamically load executable code. The term bundle is used both for the object and for the directory it represents.

Bundled resources might include such things as:

. ImagesTIFF or EPS (for instance) images used by an application's user interface components

. Sounds

. Localized character strings

. Executable code

. User Interface resourcesfiles describing the layout of user interface objects and their relationships with other objects

Each resource within a bundle usually resides in a separate file.

Localized Resources

If an application is to be used in more than one part of the world, its resources may need to be customized, or localized, for language, country, or cultural region. An application may need, for example, to have separate Japanese, English, French, Hindi, and Swedish versions of the character strings that label menu commands.

Resource files specific to a particular language are grouped together in a subdirectory of the bundle directory. The subdirectory has the name of the language (in English) followed by a .lproj extension (for language project). The application mentioned above, for example, would have Japanese.lproj, English.lproj, French.lproj, Hindi.lproj, and Swedish.lproj subdirectories.

Each .lproj subdirectory in a bundle has the same set of files; all versions of a resource file must have the same name.

The Main Bundle

Every application is considered to have at least one bundleits main bundlethe directory where its executable file is located. If the application is organized into a file package marked by a .app extension, the file package is the main bundle.

Other Bundles

An application can be organized into any number of other bundles in addition to the main bundle. For example, an application for managing PostScript printers may have a bundle full of PostScript code to be downloaded to printers.These other bundles usually reside inside the application file package, but they can be located anywhere in the file system. Each bundle directory is represented in the application by a separate NSBundle object.

By convention, bundle directories other than the main bundle end in a .bundle extension.

Dynamically Loadable Classes

Any bundle directory can contain a file with executable code. For the main bundle, that file is the application executable that's loaded into memory when the application is launched. The executable in the main bundle includes the main() function and other code necessary to start up the application.

Executable files in other bundle directories hold class (and category) definitions that the Bundle object can dynamically load while the application runs. When asked, the Bundle returns class objects for the classes (and categories) stored in the file. It waits to load the file until those classes are needed.

By using a number of separate bundles, you can split an application into smaller, more manageable pieces. Each piece is loaded into memory only when the code being executed requires it, so the application can start up faster than it otherwise would. And, assuming users will rarely exercise every part of an application, the application will also consume less memory as it runs.

The file that contains dynamically loadable code must have the same name as the bundle directory, but without the .bundle extension.

Since each bundle can have only one executable file, that file should be kept free of localizable content. Anything that needs to be localized should be segregated into separate resource files and stored in .lproj subdirectories.

Working with Bundles

Generally, you instantiate a bundle object by sending one of the bundleForClass:, bundleWithPath:, or mainBundle methods to the NSBundle class object. mainBundle gives you the NSBundle object corresponding to the directory containing the application's executable.

Initializing an NSBundle

Getting an NSBundle

Getting a Bundled Class

Finding a Resource

Getting the Bundle Directory

Stripping Symbols

Managing Localized Resources

Setting the Version