Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
As described in Overview of Software Delivery, managed installs give you more control over the installation process, which, among other things, allows you to fine-tune the user’s install experience. However, when your product is made up of a single component that doesn’t need to be placed at privileged locations in the file system, such as
/Library, you should provide users with a manual install for your product. Manual installs are faster and easier to perform for novice and expert users alike. See Manual Installs for details.
Multicomponent products benefit from managed installs because you can specify how each of a product’s components is installed. Also, remote installs—which allow you to install products remotely on several computers on a network—are based on managed installs. For more information on remote installs, see Performing Remote Installs.
Managed installs provide these features:
An automated install experience for multicomponent products
Support for upgrading your product, which may require replacing only certain components
Support for custom installs, which allow users to decide what components to install and where to install them
On a more detailed level, managed installs provide fine control over the installation process, including:
The ability to perform operations before installing, such as:
Making sure the target system meets specific criteria
Requiring administrative-user authentication before installing components at privileged locations
Performing install operations, such as quitting an application to be upgraded or launching daemons (faceless applications)
Control over details such as whether an install:
Allows the user to specify an alternate installation destination
Recommends or requires restart, logout, or shutdown after completion
Uses the ownership and access permissions of the user installing the product or those specified in the installation package
There are three ways of defining a managed install:
Distribution packages let you define the complete install experience of your product. They also provide you with a great deal of flexibility for defining the install choices users use to customize an install. Distribution packages offer you and the users of your product the best installation solution for Mac OS X–based products. Distribution packages, however, can be installed only on computers running Mac OS X v10.4 and later.
Metapackages provide some of the features distribution packages provide but can be installed on computers running Mac OS X v10.2 and later.
Component packages contain a single product component. They are usually included as part of a distribution package or metapackage but can also be installed individually in computers running Mac OS X v10.2 and later.
The following sections describe the major elements of managed installs and some of their limitations.
The central part of a managed install is the installation package, which contains your product and installation information. The following sections describe installation packages and the various types of packages you may need to create when developing a managed install for a product.
What Is a Package?
An installation package (also known as a package) is a file package (a directory that appears in the Finder as a single file) created using the PackageMaker application (
/Developer/Applications/Utilities). Packages contain a product or product component—the package’s payload—to be installed on a computer, and install configuration information that determines where and how the product is installed.
Packages have the extension
.mpkg. When a user double-clicks a package in a Finder window, the Installer application opens the package and walks the user through the installation process.
A package can specify details about four aspects of the package itself and its payload:
Read Me file
Package version number
Resource fork processing
Allowance for choosing an installation volume other than the boot volume
Installation destination on the installation volume
Relocation consent (the ability user may have to change the installation destination)
Postinstallation process action
A complex product, such as the Levon product introduced in Overview of Software Delivery, is made up of distinct components. Except for single-component products, component packages are used in conjunction with metapackages or distribution packages (described later in this chapter) to create an install experience. Specifically, component packages:
Are the basis for the mechanism that allows you to provide users a way to specify which components to install (for example, a user may not want to install a product’s tutorial files)
Let you identify required components (which must be installed) and specify the locations of components to be installed at specific locations on the installation volume
Allow you to specify system and volume requirements for the component using executable files (see Specifying System and Volume Requirements in Pre-Tiger Systems)
Component packages have the extension
.pkg. Each component package contains a single product component and specifies product information, package properties, installation properties, and install operations.
Component packages can be installed on their own or as part of the install of a multicomponent product. After the payload of a component package is installed, Installer places a receipt in the
/Library/Receipts directory of the installation volume. An installation receipt is a token that Installer uses to determine whether a package has already been installed on a system. As long as the receipt is present, subsequent installs of packages using the same package filename on the same volume are processed as upgrades.
A metapackage is an installation package that contains other installation packages. The enclosed packages can be component packages or metapackages (but not distribution packages).
Metapackages allow you to define a simple install experience for a multicomponent product. When users open a metapackage with the Installer application, they can choose to install only the components they need. Each enclosed package becomes an install choice. For example, if a product includes a tutorial-files component that the user performing the install doesn’t need, they can choose not to install that component.
Metapackages have the extension
.mpkg. Table 4-1 shows what aspects of a metapackage and the packages (component packages and other metapackages) it contains are used in the installation process.
Table 4-1 indicates that the containing metapackage specifies package properties, installation properties, and specify install operations. However, the only aspect of the metapackage used in the installation process is its product information. Conversely, for the packages the metapackage contains, all aspects except product information are used in the installation process.
A distribution package is a metapackage that specifies both product and installation information for a product. Distribution packages provide more sophisticated facilities to tailor the installation process. The major features distribution packages provide are:
Definition of the entire install experience in one place instead of having it spread out through several component packages
Definition of system and volume requirements using a requirements editor instead of executables
Install choices can contain more than one component package
Users can choose an installation destination for each install choice instead of for the entire install
Installer loads a distribution package for a multicomponent product with many component packages (and presents the user with the install experience it specifies) faster than a metapackage containing the same product
Distribution packages differ from metapackages in these areas:
They can be installed only on computers running Mac OS X v10.4 (Tiger) and later.
They must contain only component packages, not metapackages or distribution packages.
Installer ignores installation properties specified in the contained component packages (installation properties are specified by the distribution script).
Table 4-2 shows what aspects of a distribution package and the component packages it contains are used in the installation process.
Table 4-2 indicates that a distribution package specifies only product information and installation properties, and both aspects are used in the installation process. The contained packages may specify all package aspects, but only their package properties and install operations contribute to the installation process.
System and Volume Requirements
Two of the installation properties you can specify in a package are system requirements and volume requirements. These two properties define criteria the installation host must meet in order for the installation process to proceed.
System requirements specify criteria the computer or operating system must satisfy. There are two types of system requirements: recommended and required. If the host doesn’t meet a required system requirement, the installation process is canceled.
Volume requirements specify criteria each of the host’s volumes must meet in order to be considered a valid installation volume.
The Installation Process
After the Installer application opens a package, it performs the installation process in several phases:
Installer ensures that the installation host meets the system and volume requirements specified by the package.
preupgradeexecutables. If an executable returns anything other than
0, the install is cancelled.
Installer extracts the payload of component packages and copies it to the appropriate destinations.
Installer copies the component package file (with its payload stripped) to the
Library/Receiptsdirectory in the installation volume.
The following sections detail the operations that the Installer application performs in the Requirements Check, Preinstall, and Postinstall phases of the installation process for the three types of installation package files. For details on the purpose of the executable files used to define installation requirements and install operations (
postflight), see Specifying Install Operations and Specifying System and Volume Requirements in Pre-Tiger Systems.
Component Package Installation Process
This is how Installer performs the Requirements Check, Preinstall, and Postinstall phases of a component package’s installation process:
VolumeCheckon each available volume
Metapackage Installation Process
This is how the Installer application performs the Requirements Check, Preinstall, and Postinstall phases of a metapackage’s installation process:
InstallationCheckfor each package but not the top metapackage
VolumeCheckon each available volume for each package but not the top metapackage
preflightfor top metapackage
preflightfor each package
preupgradefor top metapackage
preupgradefor each package
postupgradefor each package
postupgradefor top metapackage
postflightfor top metapackage
postflightfor each package
Distribution Package Installation Process
This is how the Installer application performs the Requirements Check, Preinstall, and Postinstall phases of a distribution package’s installation process:
Installation Check script
Volume Check script on each available volume
preflightfor each package
preupgradefor each package
postupgradefor each package
postflightfor each package
The User Install Experience
The install experience that the Installer application shows users after they open an installation package has the following phases:
The first task Installer performs after opening a package is to ensure that the installation host meets the package’s installation requirements. Unsatisfied nonfatal system requirements produce a warning in user-driven installs.
When a package requires admin or
rootuser authentication, Installer displays the Authentication dialog. Users must enter the user name and password of an administrative user on the system to perform the install.
Installer always displays the Welcome page. To tailor the Welcome page, include a welcome file in the package.
If the package includes a Read Me file, Installer displays it in the Read Me page. The user can save or print this file.
If the package includes a license agreement file, Installer displays it in the License page. The user must accept the license in order to continue the installation process.
Installer checks each available volume to determine whether it meets the package’s volume requirements. It uses the information gathered in this phase in the Volume Selection phase.
Installer displays the Select Destination page if the package contains at least one package.
If the package allows both an easy install and a custom install, Installer displays the Installation Type page, which defaults to the easy install. The user can choose to perform the easy install or the custom install.
When the user clicks Install (and after admin or
rootuser authentication, if needed), Installer shows the Install page and performs the install.
Installer shows the Conclusion page when the installation process ends. In distribution packages, you can include a conclusion file that Installer shows instead of the default conclusion message.
Postinstallation Process Action
After an installation process is complete, the Installer application can recommend or mandate that the user log out of the system or restart or shut down the computer, depending on the most drastic postinstallation process action specified in the installation package. When specifying a package’s postinstallation process action, you must take into account the nature of your product and the way it interacts with Mac OS X and other executables in the system.
Limitations of Managed Installs
There are some issues and limitations of managed installs:
The Installer application does not support uninstalling products.
Installer runs only on Mac OS X.
Without proper care when specifying the ownership and access permissions of component files, it is possible to render a system unusable. Make sure you test all installer packages before shipping them to customers.
Relocation does not work in installation hosts running Mac OS X v10.3.3 or earlier.