Bundle (macOS)

In NeXTSTEP, OPENSTEP, and their successors such as macOS, iOS, iPadOS, tvOS, watchOS, and visionOS, along with GNUstep, a bundle refers to a folder organized with a specific structure and file extension that consolidates related files into a single entity.

Bundles that contain executable components encompass applications, frameworks, and plugins. These generally include one executable file along with resources like nibs, templates, images, audio files, and other media assets. Unlike platforms such as Microsoft Windows, where resources are embedded directly within executables during compilation, bundles maintain a separation between code and resources. Earlier Mac operating systems used resource forks to similarly store metadata. Analogous approaches can be found in application directories on RISC OS and the ROX Desktop environment.

Bundles without executables cover document packages (for example, iWork files) and media collections (such as the iPhoto Library).

Programmatic access to bundles is provided via the NSBundle class in the Cocoa and GNUstep Foundation frameworks, or through CFBundle within Core Foundation. Bundles frequently include an file containing metadata. The Apple Uniform Type Identifier (UTI) assigned to bundles is com.apple.bundle.

Application bundles

Application bundles are structured as directory trees with a top-level folder named using the .app suffix.

Within macOS application bundles, the initial subfolder under the root is usually named Contents. Inside this Contents directory, the MacOS folder stores the executable binary. The Info.plist file housed in Contents holds essential application information including vendor identification, executable and icon filenames, version data, and permission settings. The Resources directory contains application assets such as localized versions of nib files.

Additional standard subdirectories often found inside include PlugIns, Frameworks, _CodeSignature, and Shared Frameworks. The Frameworks folder contains frameworks that are exclusive to the application, even if other instances exist system-wide. Conversely, the Shared Frameworks directory holds frameworks shared between applications but only uses them if no newer system-provided version is available. The PlugIns directory is designated for modular extensible code components, while _CodeSignature stores information used to verify the package’s authenticity and integrity.

By default, Finder treats application bundles—also known as packages—as single opaque files without revealing their internal contents; however, users can explore their structure through the "Show Package Contents" option in the context menu.

In GNUstep environments, application code directories are typically named after the application itself but can alternatively be arranged by target CPU architecture and operating system to produce fat binarys that support multiple platforms.

macOS framework bundles

Frameworks on macOS are packaged as bundles with a top-level directory named after the framework appended by the .framework extension. Within this directory lies a Versions folder containing subfolders for each available framework version. Each versioned folder holds the dynamic library named after the framework and may also include directories like Headers, which contain header files, and Resources. Inside the Versions directory is a symbolic link called Current, pointing to the active framework version; similarly, the top-level directory links to Versions/Current. In contrast to application bundles, these framework bundles appear as normal directories in the Finder interface rather than opaque packages.

Although GNUstep supports frameworks conceptually, it generally does not implement them as bundles due to differences in how frameworks are loaded on other operating systems.

Loadable bundles

Loadable bundles consist of code that is dynamically loaded during execution, frequently utilized as plug-ins, and typically bear the .bundle extension. On macOS, these bundles can be loaded even by applications lacking inherent bundle support, allowing third-party developers to extend functionality in widely used programs such as Safari and Apple Mail. This feature originates from NeXTSTEP, with GNUstep providing similar support through the interface.

By default, the Finder treats loadable bundles—also referred to as packages—as single opaque files; however, users can explore their internal contents via the "Show Package Contents" option in the context menu.

Other bundle formats

A variety of macOS programs employ specialized bundle formats, including CandyBar with .iContainer, Aperture using .aplibrary, and VMware Fusion which utilizes .vmwarevm.

.lproj

An .lproj bundle holds localization resources for OpenStep, macOS, or GNUstep applications. These bundles generally contain language-specific .nib files, accompanied by .strings files and graphical assets such as ReadMe or license documents. Installer packages leverage these bundles for customization purposes, and they also form part of application bundles.

External links

Bundle Programming Guide at Apple Developer Connection
NSBundle documentation from GNUstep
Platypus — utility for creating application bundles encapsulating scripts
File extension information