---

PackageMaker and Installer Features

This section describes the key features provided by PackageMaker and Installer. For some features, it points to more detailed information in separate sections.

Before reading this section, you should be familiar with the information in “About Packages.”

For basic information on using PackageMaker, and on items in its user interface, see PackageMaker Help and the application’s help tags.

Contents:

Authorization and Permissions
Customizing the Installer Interface
Allowing Users to do Custom Installations
Specifying Where Software Will Be Installed
Taking Additional Control of an Installation
Localization
Prebinding
Helping Installer Find Previously Installed Software
Restarting, Logging Out, or Shutting Down
Error Reporting
Preserving Resource Fork Data
Limitations of PackageMaker and Installer

Authorization and Permissions

Installing a package may result in actions that require root or administrator privileges. PackageMaker allows you to specify whether root, administrator, or no authorization is required. Installer will then perform authorization if the user performing the installation lacks the required privileges. When authorization is required, Installer displays an authentication dialog as the first step of the installation.

It is important to ensure that the files that Installer places on a user’s computer, and the directories they reside in, have the appropriate owner and permissions. For a detailed description of this issue, see “Authorization, File Ownership, and Permissions.”

Customizing the Installer Interface

You can customize parts of the Installer application’s interface with the information and resources you build into your installation package with PackageMaker. For example, you can optionally supply localizable files that provide text for the following Installer panes:

• Introduction (or Welcome)

• Read Me

• License

In addition, you can supply an image that is displayed in the background of the installer window. You can specify how Installer scales and positions the image, and you can supply localized versions of the image. And finally, you must provide a title and you should also provide a description for your installation package, and can provide similar information for a metapackage.

For a detailed description of this feature, see “Customizing What Installer Shows to the User.”

Allowing Users to do Custom Installations

PackageMaker and Installer support custom installations, in which a user can choose which individual software items to install. To provide a custom installation, you create a separate package for each separately installable part of your software, then combine the packages in a metapackage. A metapackage is a file that encapsulates a list of packages (and possibly other metapackages) and any additional information needed to install them.

So, for example, if your software includes an application and some optional fonts, the suggested method of packaging and distribution is to package the fonts in one package, the application in another, and distribute them as a metapackage.

For more information on custom installs, see “What Is a Metapackage?” and “Anatomy of a Metapackage.”

Specifying Where Software Will Be Installed

PackageMaker and Installer provide some flexibility in specifying a destination for installing software. In working with a single package, you can

• specify a default installation directory

• arrange various components of the software to be installed in various subdirectories located off the installation directory

• require that the software be installed only on the currently booted volume; if not, the user can choose any mounted volume; but see also “Customizing an Installation With Executable Scripts” for information on checking the installation volume

• specify that the software is relocatable, which allows the user to choose a destination

When you combine individual packages in a metapackage, the user will be able to choose a destination if any of the individual packages is relocatable. If this is the case, the user will be able to choose only one destination for all relocatable packages they install, not separate destinations for each relocatable package; installed packages that are not relocatable will not be relocated. Note, however, that prior to Mac OS X version 10.3.4, relocation did not work reliably for metapackages.

For a detailed description of this feature, see “Specify the Installation Destination.”

Taking Additional Control of an Installation

PackageMaker and Installer support two mechanisms for providing additional control over an installation, described in the next sections.

Specifying Installation Requirements in a Property List

Starting in Mac OS X version 10.3, you can specify installation requirements by adding key-value pairs to the package’s information property list. You can use this mechanism to do many of the same tasks described in “Customizing an Installation With Executable Scripts,” and should make use of this mechanism where needed.

For a detailed description of this feature, see “Specifying Installation Requirements.” For more information on editing property lists, see “Examining and Modifying Property Lists.”

Customizing an Installation With Executable Scripts

PackageMaker and Installer allow you to provide scripts (or other executable files) to provide additional control over an installation. You place scripts with the specified names in the Resources directory in your package file, or in some cases in a localized directory within the Resources directory. Installer executes these files, which must have their permissions set to be both executable and readable, at well-defined times.

Installation Checking

Before proceeding with an installation, you can test whether a user’s system meets 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. This file checks the criteria you are interested in and cancels the installation, if necessary.

For a detailed description of this feature, see “Checking the Installation With InstallationCheck.”

Volume Checking

You can prevent users from installing your software on volumes that do not meet certain criteria. To do so, you supply an executable file named VolumeCheck in your installation package that determines whether a volume should be enabled or disabled as a possible installation destination.

For a detailed description of this feature, see “Checking the Installation Volume With VolumeCheck.”

Executing Scripts Before, During, and After Installation

You may need to configure the destination environment before installation or to perform additional processing after installation. The Installer application supports these capabilities by looking for certain named executable files in the installation package and, if found, executing them at specified times during installation.

For a detailed description of this feature, see “Modifying an Installation With Scripts.”

Localization

For many of the customizable features provided by PackageMaker and Installer, you can localize the information you provide:

• To localize welcome, Read Me, and license files, see “Localizing the Welcome, Read Me, and License Files.”

• To localize background images, see “Additional Tips for Background Images.”

• To localize messages shown when a user tries to install on a system that you have identified as inappropriate for an installation, see “File Placement for Installation Checking.”

• To localize messages shown when a user tries to select a volume that you have identified as inappropriate for an installation, see “File Placement for Volume Checking.”

For information on the localized folder names you can employ in packages you create, see “Localized Folder Names.”

Prebinding

Prebinding is the process of computing at build time the addresses for the symbols imported by libraries and applications, so that less work needs to be performed by the dynamic linker at runtime. Prebinding can improve the user experience by providing a faster launch, and is recommended for all applications.

If a user installs your software on a system with a set of libraries that is different than those present when the application was built, the prebinding information cannot be used and application launch is slower. Installer automatically attempts to update prebinding information for the software it installs by running the update_prebinding tool. If your software uses drag-and-drop installation, you can provide instructions for how to run this tool through a Read Me file, printed documentation, or other mechanism.

Prebinding is applicable only for Mach-O executables. (Mach-O is the native binary format for executable files in Mac OS X and is the only format supported by Project Builder.) In addition, there are some circumstances where prebinding information cannot be updated or used. For details, see the following:

• “Prebinding Your Application”

• The man pages for update_prebinding and redo_prebinding.

Helping Installer Find Previously Installed Software

The Find File feature allows you to provide Installer with rules to help it find and upgrade software from a previous installation. This feature is most useful for software that can be easily moved by the user after installation, such as application bundles.

For a detailed description of this feature, including new capabilities added in Mac OS X version 10.3, see “Finding Previously Installed Software.”

Restarting, Logging Out, or Shutting Down

PackageMaker provides several options for suggesting or requiring a restart, logout, or shutdown after installation. Note that these options should seldom be required—for example, you might only need a restart after installing system software, such as a kernel extension.

The options available in PackageMaker are:

• No Restart Required

• Recommended Restart

• Required Restart

• Shutdown Required

Logging out is an additional restart option that, as of Mac OS X version 10.3, is not available through the PackageMaker interface, but can be set directly by modifying a package’s information property list. See “Other Keys You Might Want to Modify” for details.

There currently is no indication of a restart action until the user actually starts the installation. At that point, Installer displays a message warning the user that installing the software requires them to restart their computer, and allows them to cancel the installation. Installer currently displays the same message for all restart actions.

The difference between a Recommended Restart and a Required Restart or Shutdown is that the Quit item in the Installer menu is enabled for a Recommended Restart.

Error Reporting

As you create packages, test them, and make modifications, you need feedback about just what Installer is doing. If you supply scripts to customize your installation, you’ll need to know what the scripts are doing as well.

Once you’ve launched Installer, you can choose File > Show Log to open the Installer Log window. This window displays the output from the scripts described in “Modifying an Installation With Scripts,” such as a preinstall or preupgrade script.

If you’ve supplied one of the Installation Check or Volume Check scripts described in “Checking the Installation With InstallationCheck” or “Checking the Installation Volume With VolumeCheck,” you can view script output in the Console application (located in /Applications/Utilities).

For additional information on debugging packages, see “Troubleshooting Packages and Installation.”

Preserving Resource Fork Data

Prior to Mac OS X and Carbon, application resources were stored in the resource fork of the application executable. In Mac OS X and for Carbon applications generally, resources should be put in the data fork of a separate resource file, not the resource fork of the executable. The primary reason for moving application resources out of resource forks is to enable applications to be seamlessly moved around different file systems without loss of their resources; this would include transfer mechanisms such as BSD commands, FTP, email, and Windows and DOS copy commands. Most other computing environments, including the Web, recognize single-fork files only, and tend to delete the resource fork of HFS and HFS+ files.

When you package software with PackageMaker, you supply a location from which to gather the files to be packaged. If any of these files (such as a Classic application) has a resource fork, PackageMaker supports splitting the file before packaging. Such split files will be reassembled by Installer when the package is installed. Although splitting files with resource forks is optional, if you do not split them, the resource fork data will be lost and the file will be unusable.

Because resource fork splitting changes the files that are split, it is recommended that you operate on copies of these files while creating packages.

Support for preserving resource fork data was added to PackageMaker and Installer for Mac OS X version 10.2.

Limitations of PackageMaker and Installer

The following are some issues and limitations to be aware of. For some specific examples of possible issues, see “Troubleshooting Packages and Installation.”

• Installer does not currently support uninstalling software.

• Installer runs only in Mac OS X, although it can be used to install software for previous versions of the Mac OS (to locations that are accessible when it is running).

• Prior to Mac OS X version 10.2, PackageMaker did not attempt to preserve data stored in the resource fork of a file.

• When adding localized information to packages, you can use the folder names described in “Localized Folder Names.” However, if you construct other folder names from the ISO 639 standard for language codes and the ISO 3166 standard for country codes, they may not be recognized by Installer when installing your package.

• Regarding backward and forward compatibility of packages:

  • Packages created with versions of PackageMaker prior to the one distributed with Mac OS X version 10.2 (Jaguar) work with any version of the operating system.

  • Packages created with the version of PackageMaker that shipped with the Jaguar Developer Tools in 2002 work only with Mac OS X version 10.2 and later.

  • In most cases, packages created with PackageMaker 1.1.10 (which first shipped with the December 2002 Developer Tools CD) and later work with any version of Mac OS X. However, see “Why does my package fail in Mac OS X version 10.1 but not in version 10.2?.”

• If you do not use care, it is possible to create serious permissions problems for users installing your software. It is also possible to modify a user’s system by replacing symbolic links with actual directories. For more information, see “Authorization, File Ownership, and Permissions.”

• Installer supports some features that are not currently accessible through the PackageMaker user interface. For more information, see “Editing a Property List.”

• The following features in the PackageMaker user interface are not supported:

  • On the Info pane for a package or a metapackage, information in the Version and Delete Warning fields is not used.

• An application that is distributed on multiple CDs cannot be installed from one package. If your software requires multiple CDs, break it up into smaller packages and provide installation instructions on how to install it.

• Prior to Mac OS X version 10.3.4, relocation did not work reliably for metapackages. That is, if a metapackage contained one or more relocatable packages, and the user chose an install location, the packages would not necessarily be installed in the correct location.

---