Bundles and Packages

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

• A package is any directory that the Finder presents to the user as if it were a single file.

• A bundle is a directory with a standardized hierarchical structure that holds executable code and the resources used by that code.

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.

The Advantages of Bundles

Bundles provide the following advantages for developers:

• Because bundles are directory hierarchies in the file system, a bundle just contains files. Therefore, you can use all of the same file-based interfaces to open your bundle resources as you do to open other types of files.

• The bundle directory structure makes it easy to support multiple localizations. You can easily add new localized resources or remove unwanted ones.

• Bundles can reside on volumes of many different formats, including multiple fork formats like HFS, HFS+, and AFP, and single-fork formats like UFS, SMB, and NFS.

• Users can install, relocate, and remove bundles simply by dragging them around in the Finder.

• Bundles that are also packages, and are therefore treated as opaque files, are less susceptible to accidental user modifications, such as removal, modification, or renaming of critical resources.

• A bundle can support multiple chip architectures (PowerPC, Intel) and different address space requirements (32-bit/64-bit). It can also support the inclusion of specialized executables (for example, libraries optimized for a particular set of vector instructions).

• Most (but not all) executable code can be bundled. Applications, frameworks (shared libraries), and plug-ins all support the bundle model. Static libraries, dynamic libraries, shell scripts, and UNIX command line tools do not use the bundle structure.

• A bundled application can run directly from a server. No special shared libraries, extensions, and resources need to be installed on the local system.

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:

• Application - An application bundle manages the code and resources associated with a launchable process. The exact structure of this bundle depends on the platform (iOS or macOS) that you are targeting. For information about the structure of application bundles, see Application Bundles.

• Frameworks - A framework bundle manages a dynamic shared library and its associated resources, such as header files. An application can link against one or more frameworks to take advantage of the code they contain. For information about the structure of framework bundles, see Anatomy of a Framework Bundle.

• Plug-Ins - macOS supports plug-ins for many system features. Plug-ins are a way for an application to load custom code modules dynamically. The following list identifies some of the key types of plug-ins you might want to develop:

  • Custom plug-ins are plug-ins you define for your own purposes; see Anatomy of a Loadable Bundle.

  • Image Unit plug-ins add custom image-processing behaviors to the Core Image technology; see Image Unit Tutorial.

  • Interface Builder plug-ins contain custom objects that you want to integrate into Interface Builder’s library window.

  • Preference Pane plug-ins define custom preferences that you want to integrate into the System Preferences application; see Preference Pane Programming Guide.

  • Quartz Composer plug-ins define custom patches for the Quartz Composer application; see Quartz Composer Custom Patch Programming Guide.

  • Quick Look plug-ins support the display of custom document types using Quick Look; see Quick Look Programming Guide.

  • Spotlight plug-ins support the indexing of custom document types so that those documents can be searched by the user; see Spotlight Importer Programming Guide.

  • WebKit plug-ins extend the content types supported by common web browsers.

  • Widgets add new HTML-based applications to Dashboard.

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:

• Always include an information-property list (Info.plist) file in your bundle. Make sure you include the keys recommended for your bundle type. For a list of all keys you can include in this file, see Runtime Configuration Guidelines.

• If an application cannot run without a specific resource file, include that file inside the application bundle. Applications should always include all of the images, strings files, localizable resources, and plug-ins that they need to operate. Noncritical resources should similarly be stored inside the application bundle whenever possible but may be placed outside the bundle if needed. For more information about the bundle structure of applications, see Application Bundles.

• If you plan to load C++ code from a bundle, you might want to mark the symbols you plan to load as extern “C”. Neither NSBundle nor the Core Foundation CFBundleRef functions know about C++ name mangling conventions, so marking your symbols this way can make it much easier to identify them later.

• You cannot use the NSBundle class to load Code Fragment Manager (CFM) code. If you need to load CFM-based code, you must use the functions for the CFBundleRef or CFPlugInRef opaque types. You may load CFM-based plugins from a Mach-O executable using this technique.

• You should always use the NSBundle class (as opposed to the functions associated with the CFBundleRef opaque type) to load any bundle containing Java code.

• When loading bundles containing Objective-C code, you may use either the NSBundle class or the functions associated with the CFBundleRef opaque type in macOS v10.5 and later, but there are differences in behavior for each. If you use the Core Foundation functions to load a plug-in or other loadable bundle (as opposed to a framework or dynamic shared library), the functions load the bundle privately and bind its symbols immediately; if you use NSBundle, the bundle is loaded globally and its symbols are bound lazily. In addition, bundles loaded using the NSBundle class cause the generation of NSBundleDidLoadNotification notifications, whereas those loaded using the Core Foundation functions do not.