< Previous PageNext Page > Hide TOC

Troubleshooting Packages and Installation

This section provides tips for working with executable script files, as well as a question-and-answer section to help troubleshoot common problems.

For additional information that may aid in troubleshooting, see “Test the Package.”

Contents:

Frequently Asked Questions
Working With Script Files

Frequently Asked Questions

The following are some frequently asked questions in troubleshooting installation packages.

I changed my package, so why don’t the changes show up in Installer?

This happens very commonly when an installation is canceled during testing, but you don’t quit from Installer. In this situation, Installer remains open with its current (invalid) state. As a result, you can modify the package, double-click it to launch Installer again, and see the same error because Installer is still running with its saved state.

A similar situation can occur when you modify a package definition file (.pmsp) to use a different Package_contents directory. If you don’t modify the save location, when you re-create the package it will still be in a previous directory. As a result, you may be launching an old package in the current directory, rather than the modified package in some other directory.

Why won’t my package install in Mac OS X Version 10.1?

Packages created with the version of PackageMaker that shipped with the Mac OS X version 10.2 (Jaguar) Developer Tools will work only with Jaguar and later versions of the system. However, packages created with PackageMaker 1.1.10 (which first shipped with the December 2002 Developer Tools CD) will work with any version of Mac OS X. For more information, see “Limitations of PackageMaker and Installer.”

Why doesn’t my background picture appear?

Case is important, so be sure your image file is named background.ext, where the extension is one of the following: .jpg, .tif, .tiff, .gif, .pict, .eps, and .pdf.

Your background image may not appear because it’s in the wrong place (for example, you put it in the Content directory instead of the Resources directory). Or it may not appear because you supplied some localized images, but not one for the user’s current Languages preference. To avoid the latter problem, you can place a default image at the highest level in the Resources directory.

Localization behavior is similar, but not identical, for the welcome, Read Me, and license files. For details, see “Localizing the Welcome, Read Me, and License Files.”

A user deleted my software, but still can’t reinstall it

Installer looks for a receipt with the same name as your current installation package (for example MyApp.pkg) in /Library/Receipts. If the receipt is still present, the user may not be able to reinstall the software.

Why doesn’t my metapackage work?

A common reason your metapackage doesn’t work is that the packages it contains are not in the location it expects them to be. For more information, see “Anatomy of a Metapackage.”

Why does my package fail in Mac OS X version 10.1 but not in version 10.2?

A package created on Mac OS X version 10.2 with PackageMaker 1.1.10 may fail to install on Mac OS X version 10.1 if the package requires Admin Authorization (which it might require, for example, to install an application in /Applications). The install will not authenticate and will halt with the message “You do not have enough privileges to install...”

PackageMaker 1.1.10 creates an Info.plist in the package's Contents directory, as well as a <PackageName>.info file in the package's /Contents/Resources directory. The <PackageName>.info file provides information needed to install on Mac OS X version 10.1, but in this case, the information is wrong, because the key NeedsAuthorization has the value NO instead of YES.

When this happens, you can fix your package to request authorization, and to install correctly, on Mac OS X version 10.1 by editing the <PackageName>.info file and changing the value of the key to YES. You can examine the contents of a package in the Finder by Control-clicking it and choosing Show Package Contents from the contextual menu. Once you’ve located the file in the /Contents/Resources directory, you can edit it with a text editor.

Why is Installer ignoring the version.plist information in my package?

This can happen with PackageMaker 1.1.10, because it incorrectly adds the package’s Default Location to paths in the BundleVersions.plist file (which is described in “The BundleVersions.plist File”). Your package will only have a BundleVersions.plist file if the package includes software that contains version information in a version.plist file, as described in “Supplying Version Information for Your Software.”)

Once you have created a package with PackageMaker, you can check for this problem, and correct it if necessary, with the following steps:

• In a Terminal window, use the find command to find the Archive.bom file and the BundleVersions.plist file (which you’ll use in a later step) in the package:

  find /Volumes/HD/MyPackage.pkg

  The output of this command is a listing of all the items in the package. The lines for the two files might look something like this:

  /Volumes/HD/MyPackage.pkg/Contents/Archive.bom

  /Volumes/HD/MyPackage.pkg/Contents/Resources/BundleVersions.plist

• In a Terminal window, use the lsbom command to show, from the package’s Archive.bom file, all the paths for the items to be installed. (The Archive.bom file is described in “High-Level Package Structure.”)

  lsbom -p MUGsf '/Volumes/HD/MyPackage.pkg/Contents/Archive.bom'

  Depending on the package, this may result in a large listing of files, each shown with its path. Among the lines, you should see at least one like the following:

  drwxrwxr-x root admin ./MyApp.app/Contents/version.plist

• You can display the contents of the BundleVersions.plist file with a command like the following (using the path you obtained in a previous step):

  cat /Volumes/HD/MyPackage.pkg/Contents/Resources/BundleVersions.plist

  The resulting output should show a structure of dictionaries and keys, including one or more lines showing a path for the version.plist file:

  <key>./MyApp.app/Contents/version.plist</key>

  The path should be the same as the paths in the Archive.bom file. However, if it looks like the following (that is, it has extra information in front of the expected path), then the BundleVersions.plist file is incorrect.

  <key>./Applications/MyApp.app/Contents/version.plist</key>

• To correct this problem, edit the BundleVersions.plist file and change any paths for the version.plist file to match the paths in the Archive.bom file. To do so, you delete the part of the path that comes from the Default Location, which in this case is /Applications.

Working With Script Files

This section provides some tips for working with script files or other executable files. The primary documentation for these files is located in “Checking the Installation With InstallationCheck,” “Checking the Installation Volume With VolumeCheck,” and “Modifying an Installation With Scripts.”

The following tips address some common issues.

Make sure the script is executable

If you assemble a package with PackageMaker, it will automatically set correctly named scripts to be executable. If you modify a package file directly, it’s your responsibility to ensure the executable bit is set.

And while you’re at it, make sure your script has adequate permissions (usually at least 555). For more information, see “Setting File Ownership and Permissions.”

Don’t get control characters in the script file

If you edit a script file with a GUI editor, it may insert control characters that interfere with proper execution of the script.

Quote script arguments and environment variables when you use them in a script

The paths and filenames obtained from arguments and environment variables often include spaces, so it’s a good idea to quote them in your scripts. For example, without the quotation marks around $path in the last line shown in Listing 1, the script could get an error for a volume name that included a space.

Listing 1  A partial VolumeCheck script that shows quoting

path=$1

# (Some steps omitted.)

if ([ "$path" = "Jaguar" ]) then

This full script is shown in Listing 3.

Spell script names correctly

Case matters, so be sure you match the required names (such as VolumeCheck) exactly.

Look for output in the right places

Output from InstallationCheck and VolumeCheck scripts is redirected to the Installer Log window. Output from other installation scripts is redirected to the Console window. Some scripts redirect their own output, such as to a log file. For more details, see “Viewing the Installer Log and Script Output.”

Specify a shell

Make sure the first line of your shell script specifies a shell, such as:

#!/bin/sh

Make sure your script returns a value

For success, use exit 0. For an error return, use exit <errorNumber>.

Make sure you quit Installer between tests

This one needs repeating. If an installation is canceled during testing but you don’t quit from Installer, Installer remains open with its current (invalid) state. As a result, you can modify a script, recreate the package, double-click it to launch Installer again, and see the same error because Installer is still running with its saved state.

< Previous PageNext Page > Hide TOC