< Previous PageNext Page > Hide TOC

The Installation Process

This article describes factors that can affect an installation. It also lists the typical steps that take place in the installation process.

The Installer application resides in /Applications/Utilities and is included with Mac OS X. Double-clicking an installation package file or a metapackage file launches Installer, which then takes the user through the installation process. That process can vary substantially, depending on the information the developer has supplied in the package file and the actions taken by the user.

Contents:

Factors That Affect an Installation
Installation Steps, in Order
Execution Order for a Complex Metapackage

Factors That Affect an Installation

The actual operations performed for a given installation depend on

• whether the installation is for a package or a metapackage

• whether the package or metapackage contains files such as the following for customizing the information Installer shows to the user:

  • Welcome.rtf

  • Readme.rtfd

  • License.txt

  The presence of these files (in the correct location, and with the correct spelling, including case and extension) causes Installer to present the information they contain to the user. If the files are not present or their names are misspelled, Installer shows only its default information. For information on how to use these files, see “Customizing What Installer Shows to the User.”

• whether the package’s information property list contains requirements information, which must be checked before installing (an option available starting with Mac OS X version 10.3)

  This feature is described in “Specifying Installation Requirements.”

• whether executable files with the following names are present in the package’s Resources directory:

  • InstallationCheck (described in “Checking the Installation With InstallationCheck”)

  • VolumeCheck (described in “Checking the Installation Volume With VolumeCheck”)

  • preflight, preinstall, preupgrade, postinstall, postupgrade, postflight (described in “Modifying an Installation With Scripts”)

  These executables are optional. If they are present, in the right location and with the names spelled correctly, including case, they are executed. If an executable is present but its name is misspelled, it is ignored and no error is reported.

  These files must be both executable and readable.

• whether the installation is an upgrade (a receipt file for the package exists in the /Library/Receipts directory of the destination volume, meaning the software has been installed previously) or an install (no receipt exists)

• whether the installation package is relocatable

• various interactions between the user and Installer, such as

  • authenticating (if required)

  • accepting a license agreement (if required)

  • selecting a volume

  • selecting a destination directory (if allowed)

• whether the installation package is valid:

  • a package created without problems in PackageMaker is generally valid, though that is not guaranteed

  • a package may be invalid for various other reasons, such as incorrect manipulation of its contents or incompatibilities with the user’s system

  If Installer detects an invalid package, it displays an error message and stops the installation. If this happens during package testing, you should quit Installer before further testing.

• whether the installation contains any resource forks Installer must reassemble, as described in “Preserving Resource Fork Data”

“Installation Steps, in Order” shows the actual steps for an installation, subject to the factors listed above.

Installation Steps, in Order

The following list shows the approximate order of operations for an installation. Steps marked with the • symbol are for metapackages only. “Factors That Affect an Installation” describes factors that can affect whether certain steps are performed or not.

1. A user double-clicks the icon for an installation package file.

2. Installer is launched and opens the package.

3. An Authorization pane is displayed and the user is asked to authenticate, if required.

   Failure to authenticate cancels the installation.

4. InstallationCheck is run, if present.

   • For a metapackage, InstallationCheck is run for every package that contains the script. If the metapackage itself contains the script, it is not run.

   If InstallationCheck returns anything but zero, the installation is canceled.

   Note: Starting in Mac OS X version 10.3 (v10.3), if the information property list for a package contains any requirements specifications, Installer ignores InstallationCheck (if present) and makes a pass through all the requirements, ignoring any requirements that are volume-specific. For more information, see “New and Existing Requirements Checking.”

5. The Introduction (or Welcome) pane is displayed. If the file Welcome.rtf is present, its text is displayed; otherwise, Installer uses default text.

   If the file background.tiff (or any of several other supported image types) is found, it is used as a background image in the installer window.

6. The Important Information (or Read Me) pane is displayed only if the file ReadMe.rtf is present.

7. The Software License Agreement pane is displayed only if the file License.rtf is present.

   If the user does not agree to the license, the installation is canceled.

   • For a metapackage, a License pane is displayed only if the metapackage itself contains a license file. License agreements in contained packages are not shown.

8. On entering the Select a Destination pane:

   For a package: the VolumeCheck script is run, if present, for each mounted volume.

   • For a metapackage:

   1. The VolumeCheck script is run, if present, for each mounted volume.

   2. The VolumeCheck script for each contained package is run, if present, for each mounted volume.

   If any script returns a value other than 0 for any volume, the icon for that volume is badged to indicate it cannot be used for installation. If a user clicks that icon, Installer displays an error message.

   Note: Starting in Mac OS X v10.3, if the information property list for a package contains any requirements specifications, Installer ignores VolumeCheck (if present) and makes a pass through all the requirements, once for each volume, ignoring any requirements that are not volume-specific. For more information, see “New and Existing Requirements Checking.”

9. The user selects a destination volume for the installation.

   If the software is relocatable, the user can also pick a destination directory.

   • For a metapackage, the user can pick a destination directory if the software in any contained package is relocatable.

10. Installer determines whether to perform an install or an upgrade.

11. • For a metapackage only, the user can click the Customize button.

    Installer displays the Custom Install pane, where the user chooses which items to install or upgrade.

    The user can click a button to go back and forth between the Custom Install and the Easy Install.

12. The user clicks the Install/Upgrade button.

    Note: This list of steps does not show the order in which the scripts that follow are run when installing a metapackage. For that information, see “Execution Order for a Complex Metapackage.”

13. If preflight is present, it is run.

    If preflight returns anything but 0, the installation is canceled.

14. Depending on whether the installation is an install or an upgrade, preinstall or preupgrade is run, if present.

    If preinstall or preupgrade returns anything but 0, the installation is canceled.

15. The package contents are extracted and copied to the destination volume.

16. An installation receipt is copied to the receipts directory (/Library/Receipts) on the destination volume. The receipt lists the files that were installed, but not the destination (for relocatable packages).

17. postinstall or postupgrade is run, if present.

    If postinstall or postupgrade returns anything but 0, the installation is canceled.

18. postflight is run, if present.

19. Installer handles restart, logout, or shutdown, if requested by the package.

    • For a metapackage, if any package selected for installation requires a restart action, Installer handles it.

    Note: Recall that no restart action takes place unless the user chooses to install a package on the currently booted volume.

Execution Order for a Complex Metapackage

This section shows the order of execution of the various pre-and postprocessing script files during installation of a complex metapackage, shown in Figure 1. Listing 1 shows the contents of the Umbrella metapackage, which lists one metapackage (Two_Apps) and one package (WebObjects Documentation). TwoApps metapackage in turn lists two applications (Cool_App and Mouse_Pad).

Listing 1  The contents of the Umbrella metapackage

TwoApps metapackage

    Cool_App

    Mouse_Pad

WebObjects Documentation

When each of the packages and metapackages shown in Listing 1 contained the full complement of pre-and post-processing script files (preflight, preinstall, preupgrade, postinstall, postupgrade, and postflight), the order of execution during an install (the software was installed for the first time) was as shown in the following list:

Install

1. Umbrella metapackage preflight

2. Two_Apps metapackage preflight

3. Cool_App preflight

4. Mouse_Pad preflight

5. WebObjects preflight

6. Umbrella metapackage preinstall

7. Two_Apps metapackage preinstall

8. Cool_App preinstall

9. Cool_App postinstall

10. Mouse_Pad preinstall

11. Mouse_Pad postinstall

12. Two_Apps metapackage postinstall

13. WebObjects preinstall

14. WebObjects postinstall

15. Umbrella metapackage postinstall

16. Umbrella metapackage postflight

17. Two_Apps metapackage postflight

18. Cool_App postflight

19. Mouse_Pad postflight

20. WebObjects postflight

When the metapackage shown in Listing 1 was run again, the order of execution for an upgrade (the software had been previously installed) was as shown in the following list:

1. Umbrella metapackage preflight

2. Two_Apps metapackage preflight

3. Cool_App preflight

4. Mouse_Pad preflight

5. WebObjects preflight

6. Umbrella metapackage preupgrade

7. Two_Apps metapackage preupgrade

8. Cool_App preupgrade

9. Cool_App postupgrade

10. Mouse_Pad preupgrade

11. Mouse_Pad postupgrade

12. Two_Apps metapackage postupgrade

13. WebObjects preupgrade

14. WebObjects postupgrade

15. Umbrella metapackage postupgrade

16. Umbrella metapackage postflight

17. Two_Apps metapackage postflight

18. Cool_App postflight

19. Mouse_Pad postflight

20. WebObjects postflight

To summarize from these results:

• If a metapackage contains multiple packages, all of the scripts are run in the order in which they are listed in the metapackage’s package list.

• Metapackage scripts such as preflight and postupgrade (even for embedded metapackages) are run once for the entire set of packages.

This example does not include execution order for the InstallationCheck and VolumeCheck scripts. That order is described in “Installation Steps, in Order,” and can be summarized as follows:

• Both of these scripts are run, if present, before any of the pre- and post scripts.

• For a package, the InstallationCheck script is run, if present.

  For a metapackage, for every contained package that has an InstallationCheck script, the script is run. If the metapackage itself has an InstallationCheck script, that script is not run.

• For a package, the VolumeCheck script is run, if present, for each mounted volume.

  For a metapackage

  1. The VolumeCheck script for the metapackage is run, if present, for each mounted volume.

  2. The VolumeCheck script for each contained package is run, if present, for each mounted volume.

  3. If a volume fails testing by the VolumeCheck script from any package or metapackage, it is presented as not valid for the installation package.

< Previous PageNext Page > Hide TOC