---

Managed Installs

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 /Applications or /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.

In this section:

Packages
System and Volume Requirements
The Installation Process
The User Install Experience
Postinstallation Process Action
Limitations of Managed Installs

Packages

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 .pkg or .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:

• Product information:

  • Title

  • Description

  • Welcome file

  • Read Me file

  • License file

  • Conclusion file

• Package properties:

  • Package identifier

  • Package version number

  • Resource fork processing

• Installation properties:

  • System requirements

  • Volume requirements

  • Authentication requirement

  • 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)

  • Revert consent

  • Directory-permissions overwrite

  • Postinstallation process action

• Install operations:

  • Preflight

  • Preinstall/Preupgrade

  • Postinstall/Postupgrade

  • Postflight

Component Packages

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.

Metapackages

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.

Distribution Packages

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

The central part of a distribution package is the distribution script. This is a JavaScript-based script file that contains all the information that defines an install experience. When you create a distribution package using PackageMaker, the package’s distribution script is created for you.

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:

• Requirements Check

  Installer ensures that the installation host meets the system and volume requirements specified by the package.

• Preinstall

  Installer runs preflight and preinstall/preupgrade executables. If an executable returns anything other than 0, the install is cancelled.

• Install

  Installer extracts the payload of component packages and copies it to the appropriate destinations.

• Save Receipt

  Installer copies the component package file (with its payload stripped) to the Library/Receipts directory in the installation volume.

• Postinstall

  Installer runs postinstall/postupgrade and postflight executables.

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 (InstallationCheck, VolumeCheck, preflight, preinstall, preupgrade, postinstall, postupgrade, and 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:

• Requirements Check

  InstallationCheck

  VolumeCheck on each available volume

• Preinstall

  preflight

  preinstall or preupgrade

• Postinstall

  postinstall or postupgrade

  postflight

Metapackage Installation Process

This is how the Installer application performs the Requirements Check, Preinstall, and Postinstall phases of a metapackage’s installation process:

• Requirements Check

  InstallationCheck for each package but not the top metapackage

  VolumeCheck on each available volume for each package but not the top metapackage

• Preinstall

  preflight for top metapackage

  preflight for each package

  preinstall or preupgrade for top metapackage

  preinstall or preupgrade for each package

• Postinstall

  postinstall or postupgrade for each package

  postinstall or postupgrade for top metapackage

  postflight for top metapackage

  postflight for 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:

• Requirements Check

  Installation Check script

  Volume Check script on each available volume

• Preinstall

  preflight for each package

  preinstall or preupgrade for each package

• Postinstall

  postinstall or postupgrade for each package

  postflight for 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:

• System Requirements

  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.

• Authentication

  When a package requires admin or root user 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.

• Welcome

  Installer always displays the Welcome page. To tailor the Welcome page, include a welcome file in the package.

• Read Me

  If the package includes a Read Me file, Installer displays it in the Read Me page. The user can save or print this file.

• License

  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.

• Volume Requirements

  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.

• Volume Selection

  Installer displays the Select Destination page if the package contains at least one package.

• Customization

  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.

  Note: When installing a distribution package, Installer allows users to choose individual installation destinations for each relocatable choice. With a metapackage, the Custom Install pane doesn’t allow users to choose install destinations for individual choices. With metapackages, Installer allows only one customized installation destination for all relocatable packages.

• Install

  When the user clicks Install (and after admin or root user authentication, if needed), Installer shows the Install page and performs the install.

• Conclusion

  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.

---