Anatomy of a Bundle

Unlike the Mac OS Toolbox Resource Manager, which groups resources together in a single file, CFBundle almost always stores each resource in its own file. The most common exception is CFBundle's handling of localizable strings. Strings are stored together in a strings file so that the contents can be easily cached for maximum performance.

The Carbon frameworks provide the ResourceManager API which has been modified to work with CFBundle and to support multiply localized resource forks. CFBundle also provides some simple API for properly dealing with multiply localized resource forks.

Bundles contain such things as

On disk, a bundle exists as a folder hierarchy. Here is an example of an application bundle.

	- MyBundle
		* MyApp Alias (to MacOS 8 App)
		- Support Files
			+ Frameworks
			- Executables
			    - Mac OS 8
					MyApp
					Helper Tool
			    - Mac OS X
					MyApp
					Helper Tool
			    - Solaris
					MyApp
					Helper Tool
			    - Windows
					MyApp
					Helper Tool
			* Info.plist
			* PkgInfo
			- Resources
			    - en_US.lproj
					* bird.tiff
			    		* Bye.txt
					* house.jpg
					* house-macosx.jpg
					* house-macos8.jpg
					* InfoPlist.strings
					* Localizable.strings
					+ CitySounds
			    - en_GB.lproj
					* bird.tiff
			    		* Bye.txt
					* house.jpg
					* house-macosx.jpg
					* house-macos8.jpg
					* InfoPlist.strings
					* Localizable.strings
					+ CitySounds
			    - Japanese.lproj
					* bird.tiff
			    		* Bye.txt
					* house.jpg
					* house-macosx.jpg
					* house-macos8.jpg
					* InfoPlist.strings
					* Localizable.strings
					+ CitySounds
			    - Non-localized Resources
					* Hand.tiff
					* Horse.jpg
					+ WaterSounds
		+ Plug-ins	
		+ Shared Frameworks
		+ Shared Support

- = opened folder
+ = closed folder
* = file

Though there are different types of bundles, they all share certain features. At the top level of the bundle there is always a Support Files folder. The Executable , Resources , Frameworks , Shared Frameworks , Shared Support and Plug-ins folders are optional and appear only as necessary.

For application packages that contain a Mac OS 8 executable, an alias to the executable appears at the top level of the package. This alias exists because the Mac OS 8 Finder doesn't know about application packages. The user sees the application package in the Finder as a folder that can be opened like any other. In order to launch the application, the user would open the application package and double-click the alias. For Mac OS X users the entire bundle will appear in the Finder as a single file. When this file is double-clicked, the operating system --using CFBundle --opens the package and begins executing the appropriate code for the current platform.

The Executables folder contains, as its name suggests, executable code that is grouped into folders that are named by platform. When a bundle's code is requested, CFBundle searches the Executables folder for code in the appropriate format. The names you can use when making platform-specific executable folders are Mac OS 8 , Mac OS X , Windows , HPUX , and Solaris .

The Resources folder contains resource files grouped according to language/region localization. A .lproj folder contains the region specific versions of all localizable resources. Non-localized resources are stored separately as there need be only one version of these files. Details on creating and accessing strings files are presented in Working With Localized Strings.

The Frameworks folder contains libraries that are inextricably bound to the application. These libs are revision-locked and will not be superseded by any other versions that may be available to the operating system.

The Shared Frameworks folder contains libraries that are part of the application package, but the versions of these libraries will be checked against the system registry to see if there are more recent versions available. If a more recent version is found in the system, the version in the Shared Frameworks folder is ignored. The inclusion of versioned frameworks in the application package makes it possible for an application to be completely self-contained. An application can be installed, relocated and removed with a simple drag and drop.

In addition to resources and executable code, every bundle contains two special files that hold important information describing the bundle's various attributes.

The first of these files is the Info.plist . This file contains key/value pairs stored in XML format listing information such as the name of the main executable for the bundle, version information, type and creator codes, and other meta-data that CFBundle needs. In addition to these default attributes, subsystems layered on top of CFBundle may place their own attribute info in a bundle's info plist for easy access at runtime. You are free to store any application-defined data in the info plist as well.

The other special CFBundle file is called PkgInfo . This file contains only the type and creator codes for the bundle. Although the information is redundant--it is kept in the Info plist as well--the PkgInfo file acts as a cache that improves performance for applications such as the Finder that need quick access to the type and creator codes for files.

There is also a special localized resource that goes with Info.plist called InfoPlist.strings that can contain Info.plist keys that need to be localized such as the CFBundleName key. The Info.plist file is described in More About the Info.plist File.


© 1999 Apple Computer, Inc. – (Last Updated 07 September 99)