< Previous PageNext Page >

Hide TOC

Legacy Document

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

Anatomy of a Metapackage

This section provides a detailed description of the contents of an installation metapackage. It assumes you are familiar with the information in “What Is a Metapackage?.”

You use package files for installing software and metapackage files for grouping multiple packages, which allows a user to perform a custom installation. You can also use PackageMaker to create package and metapackage definition files (with extensions .mpsp and .pmsm, respectively) to store the information you’ve entered, and to modify and recreate packages and metapackages.

High-level Metapackage Structure

A metapackage file is similar in construction to a package file, but instead of containing the software to be installed, it contains information about the packages (or other metapackages) to install. Listing 1 shows the contents of a simple metapackage.

Listing 1 Contents of a simple metapackage

Contents

Info.plist

PkgInfo

Resources

    Description.plist

    License.rtf

    ReadMe.rtf

    Simple Meta.bom

    Simple Meta.info

    Welcome.rtf

You use the PackageMaker metapackage editor to create a metapackage. To open it, you choose File > New Meta Package. You then enter information, such as the name of the metapackage, the packages or metapackages it contains, and the location of its resource folder (needed only if you provide License, Read Me, or other customizing information, as described in “Customizing What Installer Shows to the User”).

Of course, you’ll create your packages first, before adding them to a metapackage. One of the main advantages of a metapackage is that it can allow a user to do a custom installation and choose from among various items to install. To give the user more control over the process, it is worthwhile to break your software into as many pieces as you reasonably can, rather than create a single, monolithic package. For example, you might place your application, documentation, fonts, and other items in separate packages.

A metapackage shows, in the Custom Install pane, which packages will be installed and which are upgrades. The button to start the installation is labeled Install only if all of the packages have not yet been installed; otherwise it is labeled Upgrade. Items in a metapackage are installed in the order listed.

Choosing an Installation Location for the Software in a Metapackage

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.

When a Package or Metapackage Is Required

You can mark a package as required on the Info pane in PackageMaker. When you add a package to a metapackage in PackageMaker, you can also set the Attribute field for the package to Selected, Unselected, or Required (default is Selected). Together, these settings determine how the package is displayed on the Installer Custom Install pane.

On that pane, a selected checkbox means the package will be installed. If the checkbox is deselected, the package won’t be installed. If an entry is dimmed, you can’t change the setting. And if an entry is not dimmed, you can select or deselect the package for installation. Table 1 shows how each package is displayed and its resulting status (required or not required), based on the possible settings in the package and metapackage.

**Table 1** Relationship between the Required checkbox in the package and the package attribute in the metapackage (Required, Selected, Unselected)
Package	Metapackage	Custom Install checkbox in Installer	Result
Required	Selected	checked + dimmed	required
Required	Unselected	checked + dimmed	required
Required	Required	checked + dimmed	required
not Required	Selected	checked + enabled	not required
not Required	Unselected	not checked + enabled	not required
not Required	Required	checked + disabled	required

Authorization and Restart Action

A metapackage requires authorization if any of its enclosed packages requires it; otherwise, a metapackage does not require authorization. A metapackage requires the highest authorization required by any enclosed package; it also requires the highest restart action of any enclosed package.

Hiding the Packages Contained in a Metapackage

Something to consider when creating a metapackage is that the packages (or metapackages) it contains are visible to users. If you want to discourage users from installing individual packages, which is generally recommended, you can place the contained packages in a directory that isn’t visible in Finder windows. You can make a directory invisible (given standard Finder settings) by changing its name to start with a period.

One convenient way to create a metapackage that hides its packages in an invisible directory is to create a visible directory, add the packages to the directory, create and test the metapackage, then make the directory invisible by adding a period to its name using a shell command. After renaming the directory, you’ll have to edit the Info.plist file in the metapackage to point to the packages.

Suppose, for example, you have two packages, Cool_App.pkg and Mouse_pad.pkg (the same packages used in “Execution Order for a Complex Metapackage”). You could create a metapackage that installs these packages from a hidden directory by performing the following steps:

In the Finder, in the directory where you want the metapackage file to reside, create a subdirectory named contained_packages. Copy Cool_App.pkg and Mouse_pad.pkg into that directory.
Open PackageMaker and choose File > New > Meta Package to create a new metapackage.
In the Finder, drag each of the packages to the Package List pane in PackageMaker.
Choose File > Create Package and create the metapackage definition file as TestHiddenPackage.mpkg. Save this file in the same directory as contained_packages.
Choose File > Save and save the metapackage definition file as TestHiddenPackage (it will automatically get the extension .pmsm). For convenience, save this file in the directory with the metapackage.
Test the metapackage. If there are any problems, open the metapackage definition file to modify and save the metapackage, and continue testing until it works as desired.
In a Terminal window, use the cd command to change directories to the directory containing the metapackage and other files.
Use the mv command to add a period to the beginning of the contained_packages directory:
mv contained_packages .contained_packages
The period causes the directory to disappear in the Finder unless you have your Finder settings adjusted to show hidden files.
In the Finder, Control-click TestHiddenPackage.mpkg and choose Show Package Contents.
In the Finder or in a Terminal window, set the permissions on the file Info.plist in the Contents directory so that you have permission to edit it. For example, in a Terminal widow, you could use
chmod +w Info.plist
After editing, you can use chmod -w Info.plist to prevent further modifications.
Open the file and look for the key IFPkgFlagComponentDirectory. Change the value for that key from “..” to “../.contained_packages”.
Save your changes to the Info.plist file and test the metapackage. It should work the same as before but with the package files no longer visible (again, assuming standard settings in the Finder).

Note: If you know the name of an invisible directory, you can open the directory by doing a Finder search by name, and adding a search criteria for Visibility: all. Then double-click the icon for the found directory to open it.

You can also perform the following steps to show all invisible files in the Finder:

1. Type the following line in a Terminal window and press Return.

defaults write com.apple.Finder AppleShowAllFiles YES

You can turn off display of invisible files with the following line:

defaults write com.apple.Finder AppleShowAllFiles NO

2. Relaunch the Finder. You can do so by choosing Force Quit from the Apple menu, selecting the Finder, and clicking Relaunch.

For more information on editing property list files, see “Examining and Modifying Property Lists.”