Packaging Product Components

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:

1. Categorize the component.

2. Create the component package project directory.

3. Add the component files to the project directory.

4. Add executables to the project directory if the component requires them.

5. Create the component package.

6. Test the component package.

The following sections describe these tasks in detail.

Categorize the Component

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.

Table 5-2 shows the categorization of a multicomponent product.

Create the Component Package Project Directory

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/

Add the Component Files to the Package Project Directory

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

Add Executable Files to the Package Project Directory

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.

Create the Component Package

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:

1. Create a single package project.

2. Enter the package’s title and description.

3. Identify the directory that contains the component‚Äôs files (for example, the component directory in the package project directory).

4. 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

   The installation destination for the Nificky application component is /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.

   Important: Never include Mac OS X standard directories inside a component‚Äôs hierarchy. That is, do not reflect any standard part of the Mac OS X file system (in any of the file system domains) inside your component‚Äôs structure.

5. 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.

6. Identify the subdirectory in the project directory that contains executable files that specify installation requirements or install operations, if needed.

7. 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.

   Important: Installer does not use the identifier and version information specified in the Info.plist files of a package‚Äôs payload.

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.

Test the Component Package

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.