< Previous PageNext Page > Hide TOC

Checking the Installation With InstallationCheck

You can prevent users from installing your software on systems that do not meet certain criteria, such as minimum hardware requirements or the presence of required files or directories. To do so, you supply an executable file, named InstallationCheck, in your installation package that checks the criteria you are interested in. If those criteria are not met, you can cancel installation and supply a meaningful message to the user. When you cancel installation in this way, Installer exits and the installation cannot be continued.

For another possible approach to specifying requirements, see “Specifying Installation Requirements.”

Contents:

InstallationCheck Overview
File Placement for Installation Checking
Arguments and Environment Variables
Return Value for the InstallationCheck Executable
InstallationCheck Message Strings
InstallationCheck Example

InstallationCheck Overview

The Installer application looks for the InstallationCheck executable file in the Resources directory of the package. If found, the file is executed after authentication (if required) but before any other operations. See “The Installation Process” for a look at the larger picture of what happens during an installation.

InstallationCheck can use any criteria to allow or disallow installation. InstallationCheck returns a value that tells Installer whether or not to continue with installation. For details on this value, see “Return Value for the InstallationCheck Executable.”

When an installation is canceled, the value returned by InstallationCheck also indicates what message Installer displays. Installer obtains the message from an InstallationCheck.strings file you supply in the installation package. If you supply strings files for multiple locales, Installer displays the appropriate version based on the user’s current Languages preference. If you do not supply a message, Installer supplies a default message.

An InstallationCheck script is not the correct place to try to “fix” issues such as incorrect file permissions (for more on permissions, see “Authorization, File Ownership, and Permissions”). In general, you should perform installation checking only when absolutely necessary.

The following sections describe

• where the InstallationCheck file and message files are placed in the installation package

• the arguments and environment variables available to InstallationCheck

• the return values InstallationCheck uses to specify an action and a message

• the default messages supplied by Installer

• the format of messages in a message file

• a sample InstallationCheck script file

In addition, see “Working With Script Files” for tips on using executable files with PackageMaker and Installer.

File Placement for Installation Checking

Each file executed as part of an installation, including InstallationCheck, should be placed in the Resources directory of the package (or metapackage) and must have its execution bit set. In the example described in “Creating a Package,” you place script files in an Install_resources directory, then choose that directory as your Resources directory in PackageMaker.

If you place the file correctly and build the package with PackageMaker, it will automatically set the execution bit for the file. However, you may need to set explicit permissions for the executable—for more information, see “Authorization, File Ownership, and Permissions.”

Any InstallationCheck.strings message files you provide should also be placed in the Install_resources directory (and end up in the package’s Resources directory), within a localized resource directory with the appropriate name. For example, the items labeled -1- through -5- in Listing 1 show the final file placement in a test package, whose strings files are localized for English and French. For information on which localized folder names you can use, see “Localized Folder Names.”

Listing 1  Location of InstallationCheck executable and strings files in a package

Test.pkg

    Contents

        Archive.bom

        Archive.pax.gz

        Info.plist

        Resources

            Description.plist

            InstallationCheck               -1-

            English.lproj                   -2-

                InstallationCheck.strings   -3-

            French.lproj                    -4-

                InstallationCheck.strings   -5-

Warning: If no InstallationCheck.strings files are placed in localized directories, or no localized version is found for the user’s current language selection, Installer should look for a default version at the highest level in the Resources directory. Due to a bug, however, only string files in localized resource directories are currently used.

Arguments and Environment Variables

When Installer executes the InstallationCheck file, it provides four arguments:

• $1: The full path to the installation package. For example:

  /Volumes/Projects/Testing/Simple_Carbon_App.pkg

• $2: The full path to the installation destination. For example:

  /Applications

• $3: The mountpoint of the destination volume. For example:

  / or /Volumes/External_Drive

• $4: The root directory for the current System folder:

  /

Warning: The values for the variables $2, $3, and $4 are always set to /, and should not be counted on in your InstallationCheck script (even in the situation where you might expect that value).

Installer also makes one environment variable available:

• $SCRIPT_NAME: The name of the file being executed. That is:

  InstallationCheck

Return Value for the InstallationCheck Executable

InstallationCheck returns a value that Installer interprets as a pair of bit fields, as shown in Figure 1. Bits 5 and 6 of the return value determine the action—that is, whether to continue the installation or to cancel it (with a message of explanation). When an installation is cancelled, Installer exits and the installation cannot be continued.

Figure 1  Bit fields in the value returned by InstallationCheck

The bit field consisting of bits 0–4 specifies a message index. Depending on the value of the action bits (bits 5 and 6), Installer uses the index to obtain a message string from the InstallationCheck.strings file. The strings file currently must be in a localized directory, as described in “File Placement for Installation Checking.” If no strings file is provided or if the specified message cannot be found, Installer provides a default message.

Table 1 describes how Installer is intended to interpret the action bits (bits 5 and 6) in the value returned by InstallationCheck, and also notes a couple of places where, due to a bug, your results may vary from the intended results.

Table 2 shows possible bit field values for the message bit field (bits 0 through 4) in the value returned by InstallationCheck. The five bits allow for a value between 0 and 31. Table 3 shows default string values. Listing 2 shows a sample strings file.

If the package contains strings files for multiple locales, Installer displays the appropriate version based on the user’s current Languages preference. For a sample strings file, see “Strings Files for the InstallationCheck Executable.”

InstallationCheck Message Strings

As described in “Return Value for the InstallationCheck Executable,” Installer either continues the installation (without warning) or cancels it (with a message of explanation), depending on the return value from InstallationCheck.

Default Messages Provided by Installer

When the action bits are 11 (or value 96), Installer provides default message strings based on the value InstallationCheck returns in the message bit field (bits 0 to 4), as described in Table 3.

Strings Files for the InstallationCheck Executable

To display a message when cancelling an installation, you provide one or more files named InstallationCheck.strings and place them in the appropriate localized directory within the package’s Resources directory. “File Placement for Installation Checking” describes the placement of strings files in the package.

A strings file contains messages in the following format:

"number string" = "message string";

where "number string" represents a numeric value between 16 and 31, as described in Table 2 and "message string" is the string to display. Strings always end with a semicolon. An English strings file with two messages might look like the one in Listing 2.

Listing 2  A sample InstallationCheck.strings file

"16" = "Can't install unless you have a Super Drive.";

"17" = "Can’t install unless you have more than 128MB of RAM.";

Installer only displays strings from the strings file if the action bits returned by InstallationCheck are 11 (or a value of 96). So to specify an index in your strings file, you add a value between 16 and 31 to 96. For example, if the message index returned to the Installer is 112 (or a bit value of 1101000, indicating the installation should not be allowed and the message index is 16), the message displayed to the user is

Can't install unless you have a Super Drive.

The bit fields in the value returned by InstallationCheck are described in detail in “Return Value for the InstallationCheck Executable.”

InstallationCheck Example

Listing 3 shows a template for an InstallationCheck script. This script just displays its arguments and environment variables, then returns a value that causes Installer to stop the installation and display an error message. However, you can plug your installation check testing into this script.

You can examine output from InstallationCheck in the Console application (available in /Applications/Utilities). Alternatively, you can redirect output to a log file, using script statements like the following:

echo "Full volume path is: $path" >> /tmp/scripts.log

The first line in this script (#!/bin/bash) indicates that the script uses the bash shell, located in /bin. Other lines that begin with the # character are comments.

Listing 3  An InstallationCheck script that cancels installation and displays a message from the strings file

#!/bin/bash

#

# This installation script just echoes the values of the available

# arguments and environmental variables.

#

echo "START INSTALLATIONCHECK SCRIPT"

echo ""

echo "Arguments:"

echo ""

echo "\$1: the full path to the install package."

echo "     $1"

echo "\$2: the full path to the install destination."

echo "     $2"

echo "\$3: the mountpoint of the destination volume."

echo "     $3"

echo "\$4: the root directory \"/\" for the current System folder."

echo "     $4"

echo ""

echo "Environment variables:"

echo ""

echo ""

echo "\$SCRIPT_NAME: $SCRIPT_NAME"

echo ""

let retval=112

echo "\$retval = $retval"

echo "END INSTALLATIONCHECK SCRIPT"

exit $retval

< Previous PageNext Page > Hide TOC