12.1 Using PackageMaker

Apple's native format for packaging and distributing software is PackageMaker. Packages created with PackageMaker have a .pkg extension. When a user double-clicks on a package, the Installer application ( /Applications/Utilities ) is invoked and the installation process begins. These packages are bundles that contain all of the items the Installer needs.

You can also use PackageMaker to create metapackages for installing multiple packages. Metapackages contain meta-information , files, and libraries associated with a given application. Packages can also contain multiple versions of an application; typically, both Mac OS X and Classic versions.

PackageMaker documentation is available in the Help Viewer accessible from PackageMaker's Help option in the menu bar.

The basic components of a package are:

• A bill of materials ( .bom ) binary file describing the contents of the package. You can view the contents of a bill of materials with the lsbom command. After a package is installed, you can find a copy of this file in /Library/Receipts/ packagename /Contents/Archive.bom .

• An information file ( . info ) containing the information entered in the GUI application PackageMaker when the package was created.

• An archive file ( .pax ) containing the complete set of files to be installed by the package (similar to a tar archive). The file may be compressed, and have a .gz extension.

• A size calculation file ( .sizes ) listing the sizes of the compressed and uncompressed software.

• Resources that the installer uses during the installation, such as README files, license agreements, and pre- and post-install scripts. These resources are typically not installed; instead, they are used only during the installation process.

12.1.1 Setting up the Directory

To demonstrate how to create a package, we'll create a short C program and its associated manpage . Example 12-1 shows hellow.c , and Example 12-2 shows its manpage, hellow.1 .

Example 12-1. The Hello, World sample program

 /*  * hellow.c - Prints a friendly greeting.  */ #include <stdio.h> int main( ) {   printf("Hello, world!\n");   return 0; } 

Example 12-2. The manpage for hellow.c

 .\" Copyright (c) 2002, O'Reilly & Associates, Inc. .\" .Dd April 15, 2002 .Dt HELLOW 1 .Os Mac OS X .Sh NAME .Nm hellow .Nd Greeting generator .Sh DESCRIPTION This command prints a friendly greeting. 

PackageMaker expects you to set up the files using a directory structure that mirrors your intended installation. So, if you plan to install hellow into /usr/bin , and hellow.1 into /usr/share/man/man1 , you must create the appropriate subdirectories under your working directory. However, you can use a makefile to create and populate those subdirectories, so to begin with, your hellow directory looks like this:

 $  find hellow  hellow hellow/hellow.1 hellow/hellow.c hellow/Makefile 

Suppose that your hellow project resides in ~/src/hellow . To keep things organized, you can create a subdirectory called stage that contains the installation directory. In that case, you'd place the hellow binary in ~/src/hellow/stage/bin and the hellow.1 manpage in ~/src/hellow/stage/share/man/man1 . The makefile shown in Example 12-3 compiles hellow.c , creates the stage directory and its subdirectories, and copies the distribution files into those directories when you run the command make prep .

Example 12-3. Makefile for hellow

 hellow:         cc -o hellow hellow.c prep: hellow         mkdir -p -m 755 stage/bin         mkdir -p -m 755 stage/share/man/man1         cp hellow stage/bin/         cp hellow.1 stage/share/man/man1/ 

To get started, you need only hellow.c , hellow.1 , and makefile . When you run the command make prep , it compiles the program and copies the files to their locations in the stage directory. After running make prep , the hellow directory will look like this:

 $  find hellow  hellow hellow/hellow hellow/hellow.1 hellow/hellow.c hellow/Makefile hellow/stage hellow/stage/bin hellow/stage/bin/hellow hellow/stage/share hellow/stage/share/man hellow/stage/share/man/man1 hellow/stage/share/man/man1/hellow.1 

Now you're ready to launch PackageMaker and bundle up the application.

12.1.2 Creating the Package

Run PackageMaker and set the options as appropriate for your package. Figure 12-1 through Figure 12-5 show the settings for the hellow sample. The options are as follows :

Description tab

Contains items that describe the package so the person installing the package can find its name and version.

Title

The title, or name, of the package.

Version

The version number of the package.

Description

A description of the package.

Delete Warning

A custom warning message to display when a user removes the package. Mac OS X does not have a utility to uninstall a package, though.

Figure 12-1. PackageMaker's Description tab

Files tab

Contains information related to file locations and compression.

Root

This option indicates where PackageMaker can find the top-level staging directory.

Compress Archive

You should leave this option enabled, since it makes the package smaller.

Figure 12-2. PackageMaker's Files tab

Resources tab

Specifies the location of extra resources.

Resources

The Resources directory contains files, such as README files, that are used by the installer but aren't installed on the disk. See PackageMaker's help for details.

Figure 12-3. PackageMaker's Resources tab

Info tab

Specifies miscellaneous package options.

Default Location

Indicates the default target location for the package.

Restart Action

If set to Required Restart, the system must be rebooted when the installation is finished. Other options include No Restart Required, Recommended Restart, and Shutdown Required.

Authorization Action

If set to Root Authorization, the user must supply authentication to install the package. (This escalates the user's privileges to root temporarily.) Other options include No Authorization Required and Admin Authorization (if the user needs only to be an Admin user, but does not need to escalate privileges). If the package will be installed into a protected directory (such as /usr ), you should use Root Authorization.

Allows Back Rev.

Allows the user to install an older version of the package over a newer one.

Install Fat

Supports multiple architecture binaries.

Relocatable

Allows the user to choose an alternate location for the installed files.

Required

Implies that certain packages (when installed as part of a larger install) are required.

Root Volume Only

Requires the user to install the package on the current root volume (the volume from which they booted Mac OS X).

Update Installed Languages Only

Updates only the currently installed localization projects.

Overwrite Permissions

Causes the installer to change the permissions to match what PackageMaker finds in the staging area if the installer overwrites an existing file or directory.

Figure 12-4. PackageMaker's Info tab

Version tab

Specifies detailed version information.

Display name

The name of the package to use when reporting its version.

Identifier

A unique package name.

Get-Info string

The version number to use when inspecting the package in the Finder with Get Info.

Short version

An abbreviated version number.

Version: Major

A major version number (the 1 in 1.0).

Version: Minor

A minor version number (the in 1.0).

Figure 12-5. PackageMaker's Version tab

After filling in the package settings, select File Create Package to create the .pkg file. To install it, double-click on the file and install as you would any other Mac OS X package. When you quit PackageMaker, you'll be prompted to save the PackageMaker session with its currently filled in values as a .pmsp document. If you subsequently double-click your .pmsp document, PackageMaker will open with the values that were saved in the .pmsp file.