< Previous PageNext Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Modifying an Installation With Scripts

You can use scripts (or other executable files) to configure the destination environment before installation or to perform additional processing after installation.

Modifying With Scripts Overview

The Installer application looks for certain named executable files in the installation package and, if found, executes them at specified times during installation. These times take place after the user has performed any required introductory steps, such as authenticating, accepting a license agreement, specifying a volume, and so on. For a detailed description of what takes place during an installation, see “The Installation Process.”

Important: For pre- and postprocessing to work correctly, each executable tool or script must have its executable bit set. This is done automatically when you build a package with PackageMaker.

Note: Most executable files used for pre-and postprocessing are likely to be shell scripts. Such scripts can use any shell, as long as it starts with a standard #! comment to identify the shell.

The following sections describe:

the required names for executable files
when executable files are executed during installation
where executable files are placed in the installation package
the arguments passed to an executable
the environment variables available to an executable

Scripts are 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, the scripts described here should be used only when absolutely necessary.

For tips on working with scripts, see “Working With Script Files”

Executable Names

When a user clicks the Install button to start the installation process, Installer looks for the following files at specific points in the installation process and executes them if found. The files must be executable and have the names shown here:

preflight, postflight: The preflight file is executed before the installation process and the postflight file after it.
preinstall, postinstall: The preinstall file is executed before installing a single package and the postinstall file after installing it. These files are only executed for an install (the software is installed for the first time).
preupgrade, postupgrade: The preupgrade file is executed before upgrading a single package and the postupgrade file after upgrading it. These files are only executed for an upgrade (an existing version of the software is replaced, in full or in part).

When Files Are Executed

See “The Installation Process” for a look at the larger picture of what happens during an installation.

Execution Order for a Single Package

For a single package installation, Installer performs the following steps:

Executes the preflight file (if present).
For an install, executes the preinstall file (if present).
For an upgrade, executes the preupgrade file (if present).
For information on how Installer determines whether to perform an install or an upgrade, see “Installs and Upgrades.”
Extracts the package’s files and places them on the target volume.
For an install, executes the postinstall file (if present).
For an upgrade, executes the postupgrade file (if present).
Executes the postflight file (if present).

Execution Order for a Metapackage

See “Execution Order for a Complex Metapackage” for information on which files are executed and when.

Executable File Placement in a Package

All files executed as part of an installation should be placed in the Resources directory of the package. When you build a package with PackageMaker, this is done automatically. The items labeled -1- through -6- in Listing 1 show the placement in a test package.

Listing 1 Location of executable files in a package

Test.pkg

    Contents

        Archive.bom

        Archive.pax.gz

        Info.plist

        PkgInfo

        Resources

            Description.plist

            postflight      -1-

            postinstall     -2-

            postupgrade     -3-

            preflight       -4-

            preinstall      -5-

            preupgrade      -6-

Arguments

When Installer runs an executable file, it provides the following 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:
/

Environment Variables

When Installer runs an executable file, the file may have access to several environment variables. These variables are discussed next.

Possible Environment Variables

These are the environment variables that a file may have access to when executed:

$INSTALLER_TEMP: The scratch area used by Installer for its temporary work files. This variable is always set. Executable files may use this area to write data, but must not overwrite any Installer files. This directory is erased at the end of installation. For example:
/tmp/.Simple_Carbon_App.pkg.897.install
$PACKAGE_PATH: The full path to the installation package. Same as the $1 argument. For example:
/Volumes/Projects/Testing/Simple_Carbon_App.pkg
$RECEIPT_PATH: The full path to the directory containing the file being executed. This is a location to which the package has been copied. The location may vary from installation to installation. The executable can currently use this path to locate other files in the package, but this may change in the future. For example:
/tmp/.Simple_Carbon_App.pkg.897.install/Receipts/Simple_Carbon_App.pkg/Contents/Resources
$SCRIPT_NAME: The name of the file being executed. For example:
preflight or postinstall
$TMPDIR: This variable is set when the user is doing a Net or CD installation, but is not set when the user is running on a local writable file system. If set, it contains a path to a location on a writable destination volume.

The section that follows lists executable files and the environment variables they can access.

Which Environment Variables a Script Can Access

The following list shows which scripts have access to which environment variables:

preflight:
No environment variables are available.
preinstall, preupgrade:
$INSTALLER_TEMP, $PACKAGE_PATH, $TMPDIR
postflight, postupgrade:
$INSTALLER_TEMP, $PACKAGE_PATH, $RECEIPT_PATH, $SCRIPT_NAME, $TMPDIR
postinstall:
$INSTALLER_TEMP, $RECEIPT_PATH, $SCRIPT_NAME

A Sample Postflight Shell Script

Listing 2 shows a simple postflight script that merely echoes the values of its arguments and of the available environmental variables to the Installer Log window in the Installer application. To show that window, choose File > Show Log. You can print the log window contents or save them to a file. You can open the log window at any time before you quit Installer.

Alternatively, you can redirect output to a log file, using script statements like the following:

echo "Start postflight script" >> /tmp/scripts.log

Note: Although this script has been tested, you should use care in cutting and pasting it from this document. For more information, see “Troubleshooting Packages and Installation.”

Listing 2 A postflight script that displays arguments and environment variables

#!/bin/bash

# This postflight script echoes the values of the available

# arguments and environmental variables.

echo "Start postflight script"

echo ""

echo "Arguments:"

echo ""

echo "\$1: full path to the installation package"

echo "     $1"

echo "\$2: full path to the installation destination"

echo "     $2"

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

echo "     $3"

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

echo "     $4"

echo ""

echo "Environment variables available to a postflight executable:"

echo "     INSTALLER_TEMP, PACKAGE_PATH, RECEIPT_PATH, SCRIPT_NAME, and TMPDIR"

echo ""

echo "\$INSTALLER_TEMP: scratch area used by Installer for temporary work files"

echo "     $INSTALLER_TEMP"

echo ""

echo "\$PACKAGE_PATH: full path to the installation package; should be same as \$1"

echo "     $PACKAGE_PATH"

echo ""

echo "\$RECEIPT_PATH: full path to directory containing the file being executed"

echo "     $RECEIPT_PATH"

echo ""

echo "\$SCRIPT_NAME: name of the file being executed"

echo "     $SCRIPT_NAME"

echo ""

echo "\$TMPDIR: if set, a path to a location on a writable destination volume"

echo "     $TMPDIR"

echo ""

echo "End postflight script"

exit 0

Listing 3 shows the Installer Log window output from this script for one installation. Note that the output does not contain a value for $TMPDIR because that value is only set for a network or CD installation, and this output was generated for a local installation.

Listing 3 Output from postflight script in the Install Log window

    Start postflight script

    Arguments:

    $1: full path to the installation package

         /Volumes/Projects/Testing/Simple_Carbon_App.pkg

    $2: full path to the installation destination

         /Volumes/External_12_GB/Temporary Items

    $3: mountpoint of the destination volume

         /Volumes/External_12_GB

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

    Environment variables available to a postflight executable:

         INSTALLER_TEMP, PACKAGE_PATH, RECEIPT_PATH, SCRIPT_NAME, and TMPDIR

    $INSTALLER_TEMP: scratch area used by Installer for temporary work files

         /Volumes/External_12_GB/.Simple_Carbon_App.pkg.1085.install

    $PACKAGE_PATH: full path to the installation package; should be same as $1

         /Volumes/Projects/Testing/Simple_Carbon_App.pkg

    $RECEIPT_PATH: full path to directory containing the file being executed

         /Library/Receipts/Simple_Carbon_App.pkg/Contents/Resources

    $SCRIPT_NAME: name of the file being executed

         postflight

    $TMPDIR: if set, a path to a location on a writable destination volume

    End postflight script