< Previous PageNext Page > Hide TOC

Anatomy of a Package

This section provides a detailed description of the contents of a complex installation package. It assumes you are familiar with the information in “About Packages,” which introduces packages and describes the contents of a simple package.

An installation package is actually a directory, with extension .pkg, that is presented to the user as a file. You create a package with PackageMaker. The information you supply through its user interface is stored in the package. This process is described in detail in “Creating a Package.”

Double-clicking a package launches Installer. The package contains all the information Installer needs to take a user through the process of installing the packaged software.

A package has a well-defined format, with required and optional subdirectories and files. 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.

Contents:

High-Level Package Structure
Localized Folder Names
A Complex Installation Package
Additional Package Files

High-Level Package Structure

Every installation package contains one directory at the highest level, named Contents. Within that directory, all packages contain several files and a Resources directory, as shown in Listing 1. The filenames are always the same, except that if the archive file is not compressed, it does not have the .gz extension.

The files at the highest level in the package contain the software to install and information about where to install it (Archive.bom and Archive.pax.gz), as well as information about the installation (Info.plist). The PkgInfo file provides backward compatibility with previous versions of Installer.

Listing 1  Files and directories in a package’s Contents directory

Archive.bom

Archive.pax.gz

Info.plist

PkgInfo

Resources

The structure of the Resources directory is also fairly straightforward. It contains a relatively small number of files, and may also contain one or more localized directories. A Resources directory can contain these kinds of files:

• A Description.plist property list file, which provides additional information about the installation.

• Files for customizing the Installer user interface, such as a Read Me file or background image file.

• Executable files that provide additional control over the installation process, such as InstallationCheck, VolumeCheck, preflight, and postflight scripts.

• Files that provide backward compatibility with previous versions of Installer, such as a .sizes file and files that link to other files in the Contents directory.

A Resources directory’s localized directories, such as French.lproj and English.lproj, can contain the following:

• Localized versions of the Description.plist property list file

• Localized versions of the same customizing files in the Resources directory itself, such as a Read Me or license file

• Localized message files that contain text shown to the user as a result of executing an InstallationCheck or VolumeCheck script: InstallationCheck.strings and VolumeCheck.strings

Less commonly, a package can contain the files described in “Additional Package Files.”

All of these files are described in more detail in the following sections.

Localized Folder Names

You can use any of the folder names shown in Table 1 to create localized folders in the Resources folder in a package. If you construct other folder names from the ISO 639 standard for language codes and the ISO 3166 standard for country codes, they may not be recognized by Installer when installing your package.

A Complex Installation Package

Figure 1 shows the contents of a complex package that contains examples of all the types of files a package typically contains, except those described in “Additional Package Files.” You can create a package like this one by following the steps in “Creating a Package.” These files and directories include:

• Archive.bom: A binary Bill of Materials file (hence the .bom extension) that describes the files in the Archive.pax or Archive.pax.gz file.

  For a receipt file (a kind of package described in “Installs and Upgrades”), the .bom file lists the files that were actually installed. This can differ from the .bom file in the original package for two reasons:

  • If the package was relocatable, the paths to the installed files may be different from the paths in the original package.

  • If the installation is an upgrade, in certain cases Installer may not install all the files in the package. For more information, see “Specifying Version Information for Packaged Software.”

• Archive.pax.gz: A compressed archive file that contains the software to be installed. If the archive is not compressed, the .gz extension is omitted.

• Info.plist: An information property list file containing information from PackageMaker about the installation. The information is stored as a list of keys and associated values.

  For more information see “Examining and Modifying Property Lists.”

• Pkginfo: A file containing file type and creator information. Included for compatibility with earlier versions of Installer.

The package’s Resources directory contains the following files:

• background.jpg: An image file to be used as the background in the installer window if the user’s Languages preference does not match any of the localized directories.

  For information on how to provide and position a background image, see “Supplying a Background Image.”

• complex.bom: A link to the Archive.bom file. Included for compatibility with earlier versions of Installer.

• complex.info: Combines information found in the Info.plist and Description.plist files. Included for compatibility with earlier versions of Installer.

• complex.pax.gz: A link to the Archive.pax.gz file. Included for compatibility with earlier versions of Installer.

• complex.post_install, complex.post_upgrade, complex.pre_install, and complex.pre_upgrade: Included for compatibility with earlier versions of Installer. See postinstall, postupgrade, preinstall, and preupgrade for a description of the current versions of these files.

• complex.sizes: Contains information on the installed size of the package. Starting with the version of PackageMaker distributed with Mac OS X version 10.2.0, you can determine the size by querying the Archive.bom file. Included for compatibility with earlier versions of Installer.

Figure 1  The contents of a complex installation package

• English.lproj: Contains resources localized for English. In this case, these include:

  • background.jpg: Provides a background image that is displayed by the Installer on every pane.

    For more information, see “Supplying a Background Image.”

  • InstallationCheck.strings and VolumeCheck.strings: Provide localized message files that contain text shown to the user as a result of executing an InstallationCheck or VolumeCheck script.

    For more information, see “InstallationCheck Message Strings” and “VolumeCheck Message Strings.”

  • License.rtf and ReadMe.rtf: Provide localized text for the Installer License pane and Read Me pane.

    For more information, see “Supplying Text for the Introduction, Read Me, and License Panes.”

    Note that English.lproj does not contain a welcome file and relies on the welcome file in the Resources directory.

• French.lproj: Contains resources localized for French. In this case, the localized French directory contains the same files as the English directory, with one exception:

• • Welcome.rtf: Provides localized text for the Installer Introduction (or Welcome) pane.

    For more information, see “Supplying Text for the Introduction, Read Me, and License Panes.”

• InstallationCheck: An executable file, typically a shell script, that Installer runs early in the installation process. You can supply this file to check for criteria such as minimum hardware requirements.

  For more information, see “Checking the Installation With InstallationCheck.”

• postflight, postinstall, postupgrade, preflight, preinstall, preupgrade: Executable files, run by Installer at specific times, that provide additional control over the installation process.

  For more information, see “Modifying an Installation With Scripts.”

• VolumeCheck: An executable file, typically a shell script, that Installer runs once for each mounted volume. You can supply this file to check for volume criteria and restrict the volumes a user can install on.

  For more information, see “Checking the Installation Volume With VolumeCheck.”

• Welcome.rtf: Provides nonlocalized text for the Installer Introduction (or Welcome) pane. Whenever the user’s Languages preference is set for a language for which the package doesn’t provide a localized welcome file, Installer uses this version. If there is no welcome file in the Resources directory, Installer uses its own default text.

  For more information, see “Supplying Text for the Introduction, Read Me, and License Panes.”

Additional Package Files

In addition to the files described in “A Complex Installation Package,” a package may also contain the following files:

• BundleVersion.plist: A property list file created by PackageMaker when it creates an installation package. The file contains the contents of any version property list files found by scanning the items contained in the archive of files to be installed.

  This type of file is described in “Specifying Version Information for Packaged Software.”

• TokenDefinitions.plist: A property list file you create that specifies the search methods Installer should use to find files from a previous installation during an upgrade.

  This type of file is described in “Tokens Definitions and Path Mappings.”

< Previous PageNext Page > Hide TOC