PackageMaker Pro Tips

From a developer's stand point, one of the nicest features of Mac OS X is the availability of free, world class developer tools from Apple. These tools make developing software on the Mac not only significantly easier than on other platforms, but also accessible to every who has the time and bandwidth for a 300 megabyte download. One of the best and easiest to use of these tools is PackageMaker, a utility that helps you create installer packages.

In this article I will show you how to use PackageMaker to create a simple installer package. I'll also cover how to extend the package to include some of PackageMaker's more advanced features.

How Do Installer Packages Work?

Mac OS X defines packages as a way of bundling a number of related files to be used together for some purpose at a later time. Two of the more popular types of packages are installer packages and receipts. Installer packages were designed to hold files and enough information to install these files in the proper places. When an installer package is double-clicked, it's opened by an OS X program called Installer, which reads the information contained in the package and uses that information, together with user input, to install the program.

Installer also creates a receipt package, which is saved in /Library/Receipt and includes information on what was installed. These packages have a well-defined format and could be created by hand with a text editor and various command line tools, but PackageMaker puts most of the functionality needed to create an installer package into a simple tab based interface. This tool is very intuitive to use and makes creating simple installer packages trivial and more complex installer packages less troublesome.

Organizing The Files

PackageMaker can create an installer package from any set of files, even a single file. To get started, pull together a set of files to create a sample package with. Any set of files will do. Smaller files, however, are easier to handle.

Once you know the files that you want to use, put them all into a directory structure. For instance, if you'd like to have ten subdirectories each with one file, PackageMaker will keep track of the directory structure exactly as you have created it. Keep in mind that you should only include files that you want in the package in this directory and that symbolic links are copied as links and not as the files that they link to.

A Simple Installer Package

Now that we've got a directory of files ready, it's time to run PackageMaker, which comes with Apple's Developer Tools and is located in /Developer/Applications. It runs like any other OS X program and automatically creates a Single Package on startup. In order to create our simple installer package we need to add some information to the Single Package that was created by PackageMaker.

The information in PackageMaker is broken down into five different types, represented by the tabs in PackageMaker:

1. Description
2. Files
3. Resources
4. Info
5. Version

For our simple installer package we only need to fill in a few of the information fields on these tabs.

• On the Description tab we need to fill in the "Title" text box, in this case we will call set the title to "Test Package".
• On the Files tab we need to fill in "Root" with the root directory of the files that we would like to be included in the package. You should set the value of this field to the directory that we setup up before. Make sure that "Compress Archive" is checked. This option will decrease the size of the installer package and should be used for most packages you create, especially if you plan on distributing them over the Internet. (The exception to this rule is when most of your files are already compressed; hence, compressing them again will save you no space but will use quite a lot of time.)
• On the Info tab we need to fill in the "Default Location" that the installer should use. The default location can be anywhere in the file system that the user has permission for except within home directories (that is, anything in the /Users directory). For our example you should set the default location to "/Test/PackageMakerTest".

The other fields are optional, and we will delve into those a bit later. Now we need to create our package. To do this we need to choose "Create Package" from the "File" menu. This will bring up a dialog box asking for the name of the file that we would like to install. Enter "test1" and then choose the save button. A dialog box will appear showing the status of the build followed by a confirmation that the package was built. Our simple installer package is complete.

Testing our Simple Installer

If you double-click the package that we just created, you'll be dropped into the Installer program and be able to see the features that we created. A receipt from the package should also be listed in /Library/Receipts with the same name as the installer; in this case, "test1." You can examine either the installer package or the receipt package from the command line or by control-clicking and choosing "Show Package Contents". You might be interested to see how PackageMaker creates the installer package and how the files of both packages are laid out.

More Installer Features

For our simple installer package, we only used a subset of PackageMaker's features. There are a number of other fields that alter the behavior or display characteristics of the installer and some that have little real effect.

The "Version", "Description" and "Delete Warning" fields on the "Description" tab are not used in the installation process but are stored within the package. While they are not currently used, Apple has included them for possible future use in Installer or other programs, most probably an uninstaller (hence the "Delete Warning").

The "Display Name", "Identifier", "Short version", "Major" and "Minor" fields under the "Version" tab are used by the installer to determine the currently installed version, when determining if we are installing a fresh copy, an upgrade or a downgrade to a given installed package. The "Get-Info string" field information is displayed in the version field of the Finder's "Get Info" window for the package. Versioning information, while not required to make a package, is useful, especially if you plan on offering updates or new versions in the future.

The "Info" tab has the most, and the useful, options. The options on this tab relate to what the user is required to do, is able to do, or is not allowed to do. You will probably notice the behavior of the fields on this tab from installer packages that you have used in the past.

The options for the "Info" tab are

• Restart Action: used to specify if restart or shutdown is recommended or required are the installation completes.
• Authorization Action: used to specify if Admin, root or no authorization is required.
• Allows Back Rev.: if checked, an earlier version of the package may replace a newer version.
• Install Fat: if checked, the package contains files that have code for multiple platforms.
• Relocatable: if checked, allows the user to install the contents anywhere in the file system.
• Required: if checked, this is a required package not an optional install. This is used when the package is part of a larger metapackage.
• Root Volume Only: if checked, this package can only be installed on the boot volume.
• Update Installed Languages: if checked, will only update the languages that are currently installed.
• Overwrite Permissions: if checked, when updating will update the file permissions of the target files to those in the package.

Use of these features obviously depends on the type of program that you are installing and how the installation process proceeds. It's generally advisable to use as few features as possible since each feature adds time to the installation process.

Advanced Features

So far we have ignored PackageMaker's "Resources" tab. While this tab seems to be very simple, it actually provides both flexibility and programmability to installer packages made with PackageMaker. The value in the "Resources" field is the location of a directory that contains resources. These resources can be text files, pictures, and scripts; what they all have in common is that they alter the behavior of the installer.

Let's say, for instance, you don't like the first page that is displayed when Installer runs. You want to alter this "Welcome" page to include information about the software to be installed and the company that wrote it. To change this you need to create a file that contains the welcome message that you would prefer and name the file Welcome.ext where ext can be any of rtfd, rtf, html, txt. Drop that file into the Resources directory and you now have a new "Welcome" page.

Let's say that you would also like to include a page that comes after the "Welcome" page that has "Read Me" type information for instance regarding how the program runs or information on the software project. You need to create a file that contains the read me message that you want to show and name the file ReadMe.ext and drop that file into the Resources directory.

You may be thinking to yourself "I have commercial software and I need a click-through license, how do I do that?" Well as you might have guessed, you need to create a file with the license info in it and named License.ext and drop that file into the Resources directory.

Another cool resource that you can add is a background image. You name the image Background.imageext where imageext can be any of jpg, tif, tiff, gif, pict, eps, or pdf and drop it into the Resources directory. This will place a background image on all the screens that appear in Installer.

Really Advanced Features

PackageMaker has several other advanced features that add flexibility to installer packages. Language localization allows you to distribute the same package in any OS X supported language; script inclusion allows you run shell scripts during the installation process to do all sorts of things within the system; and metapackages allow you to create a package of packages which can be installed together. While we will not go into great depth on these features, here is an overview of how to use each of them to create more flexible installer packages.

• Language Localization

  Localizing Welcome, ReadMe and License pages and background images is very straight forward. First create your files as you would normally but in the new language that you would like to have the installer use. Create a directory named language.lproj in the resources directory and put the files for that language into the directory. For instance you could have a "French.lproj" or "Spanish.lproj" directory within the main Resources directory. If you want a default set of files to be used if any of the languages that you have directories for exists, then put the default set of files into the main resources directory as well.

• Scripts

  Scripts allow the installer package to do work both before and after the installation has been run. This allows the installer to do all kinds of interesting things including finding old versions of programs, finding versions of other programs, copying data from other programs, creating users, etc. The best part is that any shell script can be used, so you have the flexibility of using a simple bash script, an advanced Perl script, or even a command line program run through a script.

  Scripts are put in the Resource directory much like licenses and read me's, and can be any of 6 different types, depending on whether they are run before (called "pre") or after (called "post") installation and if they are run during all installs and upgrades (called flights), only installs or only upgrades.

  The scripts are named preflight, postflight, preinstall, postinstall, preupgrade and postupgrade.

  While we will not go into writing scripts in detail in this article, scripts provide a very precise level of control over your installation process, but can also be fairly dangerous. If you want to use scripts, be careful and test the scripts before you include them in your installer package.

• MetaPackages

  MetaPackages allow you to combine several packages into a single installer, called a metapackage. Let's say that you have a program that has two parts, a command line interface (CLI) and a graphical user interface (GUI). Some users want the CLI to be installed, while others want the GUI to be installed. To allow this we create two packages with the CLI and with the GUI. We then create a "MetaPackage" in PackageMaker by choosing "File/New/Meta Package". On the "Package List" tab we can then add our CLI and GUI packages by clicking "Add" and then altering the name of the package. We can also alter what gets installed by default by altering the "Attribute" field. Selected means it is installed by default, unselected means it is not installed by default, and required means that it is required to be installed with the program. In our example, if the GUI makes use of the CLI and most people do not want the GUI, then we would make the CLI required and the GUI unselected. We can then add resources to the metapackage much like a regular package including licenses, read me files, welcome messages, scripts and language localization. We can then create the metapackage the same way we created the regular package.

The Gift The Keeps on Giving

As you can see, PackageMaker is a simple but powerful tool for creating installer packages. Using PackageMaker for installation packages reduces the time and headache of creating installers, if you are distributing to your user or thousands of users. The advanced features of PackageMaker make not only installations but updates and patches easy to create and distribute. If you are interested in more information on PackageMaker and Mac OS X Software distribution in general check out Apple's article on software distribution. This article includes information on background image placement, creation of disk images, script use and lots of other great topics.

Andrew Anderson is a software developer and consultant in Chicago who's been using and programming on the Mac as long as he can remember.

Return to the Mac DevCenter