The Anatomy of macOS App Bundles

What’s inside a macOS app, and what does it do? macOS apps look like monolithic files, but they’re more like folders with fancy icons called bundles. Open those bundles, and you’ll find an array of files required by the application. What does this all do? An understanding of these bundles is useful for developers, administrators, game modders, Hackintosh builders, users concerned with security, and anyone troubleshooting an app.

Also read: How macOS App Sandboxing Protects Users

What Are macOS App Bundles?

As defined by Apple, a bundle is “a directory with a standardized hierarchical structure that holds executable code and the resources used by that code.” By another name, that’s an application. There’s a specific structure and format that must be adhered to by developers to ensure their app runs properly. Break those conventions, and you’ll likely break your app. If something isn’t working quite right, an application bundle might be a useful troubleshooting location.

Apps are not the only kind of bundles. Bundles are also used for files with extensions like .framework, .bundle, .plugin, and .kext. Bundles are displayed as unitary objects in Finder until you step into them by opening the bundle’s package.

Opening Application Bundles

Unlike directories, application bundles require a short dance to open.

1. Right-click on the application’s icon in “/Applications/.”

2. In the context menu, click “Show Package Contents.”

3. Double-click on the “Contents” folder to enter the app’s primary directory.

Basic macOS App Bundle Anatomy

Within the bundle’s “Contents” folder, you’ll find a number of files. All macOS apps must contain the following files at a minimum:

• Info.plist: includes mandatory configuration details along with application identifier strings.
• MacOS/Executable: the code that runs when the user launches the app that is found inside the “MacOS” folder. Without an executable, you don’t have much of a bundle.

You’re also likely to find a bevy of additional files in a few common folders:

• Plugins: extension-like mini-executables that extend the functionality of the core executable. Unlike static resources, plugins dynamically add functionality to the application.
• Resources: support files that your application relies on. This folder includes, but is not limited to, images, icons, sounds, fonts, nib files, localizations, and data stores. Unlike plugins, these resources support the core functionality of the executable.
• Frameworks: like plugins, high-level frameworks required by your app are bundles of their own. However, they employ a hierarchical different structure.
• CodeSignature: a structured plist file used to provide code signature for each part of the application. These signatures let the app and macOS verify the integrity of the application and prevent app hijacking attacks.

iOS app bundles use the same basic structure and file format, though they often appear in a different hierarchy.

Info.plist

The Info.plist is the primary digest of your application’s basic demographics. This includes your bundle identifier, which must be unique from all other bundle identifiers. To simplify this process, Apple recommends reverse domain notation, such as “com.apple.siri.launcher” or “org.videolan.vlc.” To learn more about Info.plist, check out Apple’s list of keys and consider what each key does.

This file also contains basic app information like app icon, app name, version number, copyright data, links for error reporting, and default language. By convention and system rules, the “I” in “Info” is always capitalized.

Executable

This is where the primary code of your application lives. When the application is opened, macOS will run the code contained in the executable found in the bundle’s “MacOS” directory. Nearly every application will only have a single executable, though two or more can be used for helper executables. This file is typically uninteresting to anyone except the developer of the software since it can’t be easily viewed or edited by the user.

Resources and Additional Support Files

Anything essential to your application should be included in its bundle. If its not part of the executable itself, it should go in one of the resource folders within the bundle. These resources can be stored in the primary “Resources” folder or sub-divided into different folders.

• When in doubt, most resources go in the “Resources” folder.
• Frameworks go in the “Frameworks” folder.
• Plugins go in the “Plugins” folder.
• Localization files (.lproj directories) go in the Resources folder.

Outside those requirements, Apple provides many suggestions and conventions that should be followed unless you have a defensible reason to do otherwise.

Conclusion

macOS applications are contained within bundles, which are hierarchical containers for application files. The basic structure is the same for every application. The files most interesting to the user are found in the Resources folder inside the app’s bundle.