About Bundles

Bundles are a convenient way to deliver software in macOS and iOS. Bundles provide a simplified interface for end users and at the same time provide support for development. This chapter provides an introduction to bundles and discusses the role they play in macOS and iOS.

Bundles and Packages

Although bundles and packages are sometimes referred to interchangeably, they actually represent very distinct concepts:

Packages provide one of the fundamental abstractions that makes macOS easy to use. If you look at an application or plug-in on your computer, what you are actually looking at is a directory. Inside the package directory are the code and resource files needed to make the application or plug-in run. When you interact with the package directory, however, the Finder treats it like a single file. This behavior prevents casual users from making changes that might adversely affect the contents of the package. For example, it prevents users from rearranging or deleting resources or code modules that might prevent an application from running correctly.

Whereas packages are there to improve the user experience, bundles are geared more toward helping developers package their code and to helping the operating system access that code. Bundles define the basic structure for organizing the code and resources associated with your software. The presence of this structure also helps facilitate important features such as localization. The exact structure of a bundle depends on whether you are creating an application, framework, or plug-in. It also depends on other factors such as the target platform and the type of plug-in.

The reason bundles and packages are sometimes considered to be interchangeable is that many types of bundles are also packages. For example, applications and loadable bundles are packages because they are usually treated as opaque directories by the system. However, not all bundles are packages and vice versa.

How the System Identifies Bundles and Packages

The Finder considers a directory to be a package if any of the following conditions are true:

  • The directory has a known filename extension: .app, .bundle, .framework, .plugin, .kext, and so on.

  • The directory has an extension that some other application claims represents a package type; see Document Packages.

  • The directory has its package bit set.

The preferred way to specify a package is to give the package directory a known filename extension. For the most part, Xcode takes care of this for you by providing templates that apply the correct extension. All you have to do is create an Xcode project of the appropriate type.

Most bundles are also packages. For example, applications and plug-ins are typically presented as a single file by the Finder. However, this is not true for all bundle types. In particular, a framework is a type of bundle that is treated as a single unit for the purposes of linking and runtime usage, but framework directories are transparent so that developers can view the header files and other resources they contain.

About Bundle Display Names

Display names give the user some control over how bundles and packages appear in the Finder without breaking clients that rely on them. Whereas a user can rename a file freely, renaming an application or framework might cause related code modules that refer to the application or framework by name to break. Therefore, when the user changes the name of a bundle, the change is superficial only. Rather than change the bundle name in the file system, the Finder associates a separate string (known as the display name) with the bundle and displays that string instead.

Display names are for presentation to the user only. You never use display names to open or access directories in your code, but you do use them when displaying the name of the directory to the user. By default, a bundle’s display name is the same as the bundle name itself. However, the system may alter the default display name in the following cases:

  • If the bundle is an application, the Finder hides the .app extension in most cases.

  • If the bundle supports localized display names (and the user has not explicitly changed the bundle name), the Finder displays the name that matches the user’s current language settings.

Although the Finder hides the .app extension for applications most of the time, it may display it to prevent confusion. For example, if the user changes the name of an application and the new name contains another filename extension, the Finder shows the .app. extension to make it clear that the bundle is an application. For example, if you were to add the .mov extension to the Chess application, the Finder would display Chess.mov.app to prevent users from thinking Chess.mov is a QuickTime file.

For more information about display names and specifying localized bundle names, see File System Overview.

The Advantages of Bundles

Bundles provide the following advantages for developers:

Types of Bundles

Although all bundles support the same basic features, there are variations in the way you define and create bundles that define their intended usage:

Although document formats can leverage the bundle structure to organize their contents, documents are generally not considered bundles in the purest sense. A document that is implemented as a directory and treated as an opaque type is considered to be a document package, regardless of its internal format. For more information about document packages, see Document Packages.

Creating a Bundle

For the most part, you do not create bundles or packages manually. When you create a new Xcode project (or add a target to an existing project), Xcode automatically creates the required bundle structure when needed. For example, the application, framework, and loadable bundle targets all have associated bundle structures. When you build any of these targets, Xcode automatically creates the corresponding bundle for you.

If you use make files (instead of Xcode) to build your projects, there is no magic to creating a bundle. A bundle is just a directory in the file system with a well-defined structure and a specific filename extension added to the end of the bundle directory name. As long as you create the top-level bundle directory and structure the contents of your bundle appropriately, you can access those contents using the programmatic support for accessing bundles. For more information on how to structure your bundle directory, see Bundle Structures.

Programmatic Support for Accessing Bundles

Programs that refer to bundles, or are themselves bundled, can take advantage of interfaces in Cocoa and Core Foundation to access the contents of a bundle. Using these interfaces you can find bundle resources, get information about the bundle’s configuration, and load executable code. In Objective-C applications, you use the NSBundle class to get and manage bundle information. For C-based applications, you can use the functions associated with the CFBundleRef opaque type to manage a bundle.

For information about how to use the programmatic support in Cocoa and Core Foundation to access bundles, see Accessing a Bundle's Contents.

Guidelines for Using Bundles

Bundles are the preferred organization mechanism for software in macOS and iOS. The bundle structure lets you group executable code and the resources to support that code in one place and in an organized way. The following guidelines offer some additional advice on how to use bundles: