After breaking down a product into distinct components (such as applications, frameworks, fonts, documentation, and so on), you create an installation package for each of the product’s components. An installation package is a file package that contains one component and information about the package and its payload. See “What Is a Package?” for more information about packages.
The Installer application can open a package and place its payload on a user’s system. Installation packages whose payload is a component of a multicomponent product are known as component packages.
To create a component package, you perform the following tasks:
Categorize the component.
Create the component package project directory.
Add the component files to the project directory.
Add executables to the project directory if the component requires them.
Create the component package.
Test the component package.
The following sections describe these tasks in detail.
There are several types of product components available in Mac OS X. Some examples are application packages (file packages that contain an application’s executable code and resources), frameworks (directories that contain shared executable code and resources), font files, and plug-ins. Categorizing a component helps you determine the appropriate installation destination for it. Table 5-1 shows some component categories and corresponding installation destinations. See File System Overview for detailed information.
Type | Destination |
---|---|
Application |
|
Framework |
|
Font |
|
Documentation |
|
Command-line tool |
|
Table 5-2 shows the categorization of a multicomponent product.
Component | Component type | Installation destination |
---|---|---|
| Application |
|
| Documentation |
|
| Framework |
|
The component package project directory stores the component’s files, the package project file, and other installation files. For easy identification, you should include the version number of the component in the name of the project directory. For example, Listing 5-1 shows the names of the project directories for the three components of the Levon product.
Listing 5-1 Component-package project directories for a multicomponent product
LevonApp-1.0.0/ |
LevonDoc-1.0/ |
SharedServicesFwk-1.0/ |
Inside the package project directory, create a directory to hold the component files, as shown in the highlighted lines in Listing 5-2.
Listing 5-2 Adding component files to component-package project directories
LevonApp-1.0.0/ |
component/ |
Levon.app |
LevonDoc-1.0/ |
component/ |
Levon_User_Guide.pdf |
SharedServicesFwk-1.0/ |
component/ |
SharedServices.framework |
If your component requires tailored install operations or needs to specify system and volume requirements, add the extras
directory to the package project directory containing the appropriate executables. Listing 5-3 highlights the extras
directories in two package project directories.
Listing 5-3 Adding executables to component-package project directories
LevonApp-1.0.0/ |
component/ |
Levon.app |
extras/ |
InstallationCheck |
VolumeCheck |
preflight |
postupgrade |
LevonDoc-1.0/ |
component/ |
Levon_User_Guide.pdf |
SharedServicesFwk-1.0/ |
component/ |
SharedServices.framework |
extras/ |
InstallationCheck |
VolumeCheck |
preflight |
postinstall |
postupgrade |
See “Specifying Install Operations” and “Specifying System and Volume Requirements in Pre-Tiger Systems” for details on install operations and executable-based installation requirements.
After you have created the package project directory, you use PackageMaker (/Developer/Applications/Utilities
) to create the component package project file.
To create a component package in PackageMaker:
Create a single package project.
Enter the package’s title and description.
Identify the directory that contains the component’s files (for example, the component
directory in the package project directory).
Edit the component directory’s ownership and access permissions settings using the File Permissions editor.
The files that the Installer application places on the installation host have the ownership and access permissions specified in the component files in the package. Therefore, you must set up the owner and access permissions of component files appropriately before generating the installation package; otherwise, users may have difficulty manipulating those files after they are installed. In most cases, the owner should be root
and the group admin
. Use the permissions recommended in the File Permissions editor.
Overwriting directory access permissions: The Installer application assigns access permissions to directories that don’t exist on the installation volume but are part of a product’s structure. (These directories are specified in the component directory when you created the component package.) When a directory that’s part of the component hierarchy already exists on the installation volume, its permissions are modified only if the package specifies that directory permissions must be overwritten. Because modifying the permissions of existing directories in Mac OS X—especially standard directories in the local and system domain—may impair the normal operation of the installation host, you should not generally have packages overwrite directory permissions. However, components that use an internal hierarchy that doesn’t include Mac OS X standard directories may need to overwrite the access permissions of their internal directories to ensure a successful install.
To illustrate this situation, analyze the structure of the Nificky component directory, shown here.
component/ |
Nificky/ |
Nificky.app |
ReadMe.rtf |
/Applications
. Therefore, after the component is installed, the Applications
directory on the installation volume contains the Nificky directory, which itself contains the Nificky.app
file package and the ReadMe.rtf
file. But, if Applications/Nificky
already exists on the volume and its access permissions do not allow modification, the install fails. Specifying that the installation package for the Nificky application overwrite directory access permissions ensures that the Installer application modifies the permissions on Applications/Nificky
to allow it to place files within the directory. The access permissions of the Applications
directory are untouched.Set the installation destination for the component, and specify an appropriate authentication level and postinstallation process action, if needed.
Installing into the user’s home directory: One way to place files into a user’s home directory is to specify /Users/Shared
as the installation destination and use an install operation to move the product files into the current user’s home directory (specified by the $HOME
environment variable). See “Specifying Install Operations” for details.
Identify the subdirectory in the project directory that contains executable files that specify installation requirements or install operations, if needed.
Set the package identifier and version number.
A package’s identifier and version number help the Installer application determine the best way to update a product’s files during an install on a system on which the package has already been installed. You must set these two package properties for every package you create.
For applications and frameworks, use the bundle identifier (CFBundleIdentifier
) specified in their Info.plist
files as a starting point. For example, if the bundle ID of an application is com.mycompany.Levon
, the package identifier should be com.mycompany.Levon.pkg
. Keep in mind that the package identifier must be unique. (For detailed information on the CFBundleIdentifier
and other Info.plist
keys, see Runtime Configuration Guidelines.)
Note: The Info.plist
file is located in the Contents
directory of application and plug-in file packages (use the Finder Show Package Contents command to reveal the contents of file packages). In a framework, the Info.plist
file is located in the Resources directory.
The package version for application, framework, and plug-in component packages should be the value for the CFBundleShortVersionString
property of the component they contain. In framework component packages, use the value for the CFBundleVersion
property. For other component types, choose an appropriate package identifier and package version number.
After you’ve defined a package, use the PackageMaker Build command to generate the component package (.pkg
) file. You can also save the package project file in the project directory for future use.
Before adding a component package to a metapackage or a distribution package, it’s good practice to ensure that the package installs correctly on its own. You accomplish this task by opening the package in the Installer application and performing the installation process, confirming that the component files are installed correctly.
Last updated: 2006-07-24