---

About Packages

Packages are a key part of distributing and installing software with PackageMaker and Installer. The terminology and concepts described in this section will help you work effectively with packages.

Contents:

What Is a Package?
What Is a Metapackage?
File Types Created by PackageMaker
A Simple Package
The Package as a Black Box

What Is a Package?

The word “package” can have a number of different meanings. This document uses the term installation package (or simply package) to refer to the package files created by PackageMaker. These files have the following properties:

• They have the extension .pkg.

• They are presented by the Finder as a single file (though you can examine their contents by Control-clicking on the package and choosing Show Package Contents from the contextual menu, or by using the find command in a Terminal window).

• They contain various files and directories in well-defined locations within the package

• The files and directories in a package together provide the information needed by the Installer application to present the packaged software for installation.

• Double-clicking a package launches the Installer application.

During installation, Installer creates another package file (with extension .pkg) to serve as an installation receipt, and stores it in /Library/Receipts. This document uses the term installation receipt (or simply receipt) to refer to this kind of package.

For more information on receipts, see “Installs and Upgrades.” For more information on the file types created by PackageMaker, see Table 1. For information on when you might want to edit the contents of a package directly, see “The Package as a Black Box.”

What Is a Metapackage?

A metapackage is a file that includes a list of packages (and possibly other metapackages) and any additional information needed to install them; the packages themselves, however, are not actually contained in the metapackage. Double-clicking a metapackage launches Installer. During installation for a metapackage, at the point where a user can click a button to install or upgrade the software, they also have the option of clicking a Customize button to perform a custom install.

The Custom Install pane lets the user choose from the packages contained in the metapackage (and in any metapackages it may contain). The user can also click an Easy Install button to go back to the Easy Install pane. The package creator has the option of making any package (or metapackage) in a metapackage be required, in which case the user cannot deselect that package (or metapackage). Figure 1 shows the Custom Install pane for a metapackage that is being installed on a volume named “Mac OS X version 10.3”. The metapackage contains one package (WebObjects Documentation) and one metapackage (Two Apps), which in turn contains two packages (Cool App and Mouse Pad). In this example, neither the metapackage nor any of the packages is required.

It’s a good idea to give users as much flexibility as possible, so you should generally create packages for any component of your software that a user might reasonably wish to install separately, then combine them in a metapackage.

For additional details on working with metapackages, see “Installs and Upgrades,” “Anatomy of a Metapackage,” and “Execution Order for a Complex Metapackage.”

File Types Created by PackageMaker

Table 1 lists the kinds of files PackageMaker can create. Each of these files has a specific file extension and serves a specific purpose, as described in the table.

A Simple Package

A package is a directory, presented by the Finder as a single file, that contains all the information the Mac OS X Installer application needs to install your software. That includes the software itself, as well as files that are used only during the installation process. The software to be installed is typically stored a compressed archive, and may include application bundles, frameworks, documentation, and other kinds of files. The files used only as part of the installation process can include localized files for customizing the installation, scripts for checking the installation environment or performing other operations, and property list files created by PackageMaker to store various information about the installation.

Figure 2 shows the contents of a very simple installation package file.

To display the contents of an installation package (or any other directory displayed in the Finder as a single file), Control-click the file and choose Show Package Contents from the contextual menu.

For a detailed description of the files in an installation package file, see “Anatomy of a Package.”

The Package as a Black Box

Some developers may be able to treat a package as a “black box,” created by PackageMaker and modified only through PackageMaker. In this scenario, you save a corresponding package definition (.pmsp) file for each package file you create and, if you need to change the package, you open the package definition file in PackageMaker, use the application user interface to make changes, then create a new package file.

However, you may find it convenient to modify the contents of a package file directly. For example, it can be faster to test and modify a package’s script files in the Finder or in a shell than to edit and resave the package in PackageMaker each time you modify a script. Or you might want to modify the Resources directory directly to test localized resources.

Additionally, information for some features cannot currently be supplied through the PackageMaker user interface, so if you need those features, you must modify the package’s Info.plist or Description.plist files directly. A primary example of this is the feature, added in Mac OS X version 10.3, which allows you to specify requirements for your installation package by editing the package’s property list. For more information, see “Examining and Modifying Property Lists” and “Specifying Installation Requirements.”

Some developers may also choose to modify package files directly as part of automating the build process or automating the process of distributing software. Those topics are not described in this document.

Finally, you may choose to modify packages directly as a convenience, rather than having to go back through PackageMaker each time you need to make a change. If so, be sure you consider some of the potential issues described in “Troubleshooting Packages and Installation.”

---