A brief history of bundles

In the elegant simplicity of Classic Mac OS, applications were intended to be single files with much of their contents stored in their resource fork, where they kept all the paraphernalia they required, from code resources to windows, icons and dialogs.

This is QuarkXPress version 4.11 from around 2000, its resources displayed in the resource editor ResEdit. The app icons shown are stored in a resource of type BNDL, a ‘bundle’, but not in the later sense of the term.

In this respect, as in many others, Mac OS X abandoned its Mac past in favour of what had been developed in NeXTSTEP, here a structured directory termed a bundle. These were primarily used for constructs that the user was intended to see as a single item, usually containing executable code and its resources, forming applications, frameworks and plug-ins.

Early bundles

At first, there were two types of bundle in use. Versioned bundles consisted of a file containing executable code, together with a directory containing resources and more directories with further resources, without any Contents directory or top-level property list. New-style bundles contained a minimum of a top-level directory named Contents, and inside that a property list named Info.plist, as continues today. Some implementations of the new-style bundle also contained a file named PkgInfo containing type and creator information that had originated in Classic Mac OS; although apparently not mandatory, PkgInfo has survived to the present in app bundles.

The information property list Info.plist contained key-value pairs in XML format, for attributes such as:

bundle name,
name of bundle executable,
version,
type and creator codes, inherited from Classic Mac OS and duplicating those in PkgInfo,
app and document icons,
other metadata.

Current bundles are direct descendants of those new-style bundles.

Fat apps with support for both Classic Mac OS and Mac OS X had a more complex structure. Inside their Contents directory, they had the following:

MacOSClassic directory, containing the Classic version of their executable code,
MacOS directory, containing the Mac OS X version of their executable code,
Info.plist file,
Resources directory, containing resources such as icons, images, and directories of localised resources such as nibs and strings,
Other directories such as Frameworks, PlugIns, SharedFrameworks and SharedSupport as necessary.

To enable that to run in Mac OS 9, alongside the Contents directory was an alias to the executable code in Contents/MacOSClassic.

The Finder recognised a directory as a bundle and treated it as a single entity if:

the directory name had an extension for a standard bundle type, such as .app, .bundle, .framework, .plugin, .kext and others, or
the directory name had an extension identifying it as a type set as a bundle (or package), such as .rtfd, or
the directory had its Finder bundle bit set.

Frameworks are an exception to the general rule that the Finder displays bundles as single items, as they are still shown as folders. However, the original reason given by Apple for this, “so that you can browse their header files”, no longer applies.

Packages

By 2005, Apple was drawing a distinction between bundles with the formal structure given above, including the Info.plist inside a Contents directory, and other directories presented to the user as a single item, such as RTFD documents, that had different structures and are strictly termed packages. For example, the Rich Text Format Directory (RTFD) favoured by Apple consists of:

Contents, a directory containing a PkgInfo file
files containing graphics to be included within the documents
TXT.rtf, a Rich Text Format file containing the styled text.

This is closer to the versioned bundles of early Mac OS X. Currently, there are distinct UTI types for com.apple.bundle and com.apple.package, with bundles conforming to both, but packages only to the latter. Unfortunately, this distinction between bundles and packages has largely fallen into disuse because of the name collision with Installer packages.

More recently, in its iWork documents, Apple has moved away from plain document packages or bundles to a custom package in a Zip-compressed archive, for example in .pages documents, which still conform to com.apple.package although they can’t be opened in the Finder. Compression has also become popular with space-inefficient formats such as XML.

Signatures

The introduction of code signing in 2007 brought the requirement to store signature information including code directory hashes (CDHashes) inside the app bundle. This has been implemented using an additional directory, _CodeSignature, containing a CodeResources file. Single-file command tools can instead have their signature embedded in their binary.

Most recently, in 2018, notarization has added the requirement to accommodate its ‘ticket’, which is ‘stapled’ as another CodeResources file inside the Contents directory. However, stapling isn’t required, as notarization can be verified by looking up the CDHashes with Apple’s online service in iCloud. There’s also still no way to staple a notarization ticket to a single-file binary.

Platform-specific code

The transition from Classic Mac OS to Mac OS X used separate directories for executable code within app bundles, with that named MacOS containing code to be run in Mac OS X. When the Mac architecture changed from PowerPC to Intel, from 32-bit to 64-bit, and again from Intel to Arm, app bundles have continued to use the MacOS directory, with executable code for each supported architecture being saved within each file.

Key dates

1984 single-file application with resource fork, type and creator codes
2001 Mac OS X 10.0 Cheetah, with versioned and new-style bundles, PkgInfo for type and creator codes, Info.plist in new-style bundles
2005 bundles and packages
2007 Mac OS X 10.5 Leopard, _CodeSignature directory for code signatures
2018 macOS 10.14 Mojave, CodeResources for notarization ticket.

References

Apple’s Bundle Programming Guide, last updated to 2017
Apple, Inside Mac OS X, System Overview, July 2002, PDF no longer available online.