Publishers of technology books, eBooks, and videos for creative people

Home > Articles

  • Print
  • + Share This
This chapter is from the book

Creating Packages

With the number of complex files in a package, creating a package can seem intimidating at first. The Apple utility PackageMaker simplifies the process by letting you create packages using a setup assistant, add components to a distribution project, or manually create a package or metapackage project.

Package Setup Assistant uses a familiar interface for package creation. It is intended to allow for quick and easy package creation with intelligent defaults. If you need different custom settings, simply open the package or metapackage in PackageMaker.

To open Package Setup Assistant, select File > New and click Assist Me. The assistant will walk you through the package–creation process in the following steps:

  1. Welcome—Prompts for basic package information.
  2. Contents—Prompts for the items to install.
  3. Bundle Identifiers—Displays what packages will be created, and prompts for bundle identifiers and versions.
  4. Metadata—Prompts for package metadata. Not displayed when creating a distribution.
  5. Resources—Prompts for resources (for example, License, ReadMe, and so on).
  6. Package Creation—Will create all packages and bundle them in a metapackage or distribution if necessary.

Creating a Distribution Project

Distribution projects can be created for systems that run Mac OS X v10.4 and higher (as well as Mac OS X Server v10.4 and higher). Although a distribution project is similar to a metapackage, it provides more flexibility in customizing the Installer interface. This flexibility is provided by a distribution script, which is XML combined with JavaScript.

To create a minimal, functional distribution project, do the following:

  1. Create the packages to be bundled.
  2. Using PackageMaker, give the distribution a title in the Installer Interface pane.
  3. Create choices for the items you want to install. Multiple packages can be attached to a single choice.
  4. Add the packages to the appropriate choices.
  5. Make sure the information for each package is correct.
  6. Build the distribution by choosing Project > Build.

    After the distribution is built, you have the option of verifying the build while still within PackageMaker.

The following figure shows a distribution project window with various authentication and postinstall actions already selected.

Determining Package File Structure

The first step in manually creating a package project with PackageMaker is to create a folder hierarchy containing the files to be installed. This arrangement should represent the folder hierarchy of the system that will receive the installed files.

Begin by creating a folder that represents the root folder of where your files will be installed, as shown in the following figure. In most cases, your destination root folder will correspond to the root folder (/) of the target file system, but this may not always be the case. If, for example, you were creating a package just to install fonts, the root folder could represent /Library/Fonts. The folder structure for the installer is incredibly important. Folders that do not exist will be created, while folders that do exist can have the existing items replaced by the ones in the package.

Once you have the destination root folder, you populate it with files that you want installed by your package. The files are placed within a folder structure that matches where they will be placed on the target computer, relative to the destination root. Any folders that are in the destination root layout but are not on the target computer will be created automatically when the package is installed. Only use copies of the files with which you want to populate the folder hierarchy, because PackageMaker will alter the files during the package–creation process.

Creating a Package Manually in PackageMaker

After you have created the folder hierarchy containing the files to be installed and included the resources, run the PackageMaker utility to convert the folder hierarchy into a package, using the Single Package Project option.

The PackageMaker window has five panes:

  • Installer Interface— Allows you to add description information to the package. The Title field allows you to set the title for the Installer window. The title and description will be displayed to the user if the package is delivered as part of a metapackage.

    In Mac OS X v10.4, this pane also includes a button to open the Installer Interface Editor, which lets you drag and drop to change or add new text files and background image resources. Some users may find using the Install Interface Editor more convenient than placing the files in a resources folder.
  • Contents— Allows the package builder to point to a folder containing the files to be added to the package. This path is the location of the files that will be stored inside the package. Click File Permissions to examine and change the permissions of the files that will be stored in your package.

The Contents pane also allows you to add file filters and locator definitions (used to locate and identify previously installed software). Generally you will want to compress the archive,so your resulting package will be smaller. In most cases, you’ll want to remove the .DS_Store files, but do not discard the resource forks. Including .DS_Store files or discarding resource forks can lead to problems with the appearance and operation of your installed files on the target computer.

  • Configuration— Allows the package builder to configure the installation of the package contents. More details about this pane are included in the next section, “Setting Configuration Options.”

  • Scripts— Allows the package builder to point to a folder to include any necessary resources to the package, including scripts, tools, and documents such as license or welcome text files.

  • Package Version— Allows the package builder to set version and display information. This includes a unique identifier for the package. Since this must be unique, consider using your domain name in reverse dot notation, also known as a Java-style package name. For example, for a package called MyGreatSoftware at Apple, use as the identifier.

After you fill in the required information in PackageMaker, choose File > Save to save the configuration, and then choose Project > Build to create the package.

Setting Configuration Options

The Configuration pane lists the options on the package. You can specify whether a restart and/or authorization is required. Also, you can set flags that affect the installation.

Here are the various options available in the Configuration pane:

  • Default Location— The location of the root of the folder structure on the target computer. Note that if you are installing files into multiple folders, this must be the highest enclosing folder. For example, if you are installing files in /private/etc, /Applications, and /Library, you must specify the default location as /.

  • Authentication— Specify one of the following options:

    • None— User is not prompted for an admin password, and new files and folders will be owned by the user running Installer.

    • Admin— If the user is signed on as a normal user, the user is prompted for an admin user name and password. Files and folders will have the ownership specified in the package, except when root is specified.

    • Root— All users are prompted for an administrator user name and password. Files and folders will have the ownership specified in the package under all circumstances.

  • Post-Install Action— Specify one of the following options:

    • None— Installer can be closed after installation.

    • Recommended Restart— User will be prompted to restart after installation but will have the option to quit without restarting.

    • Required Restart— User will be prompted to restart after installation and won’t be able to quit Installer without restarting.

    • Shutdown Required— User will be prompted to shut down after installation and won’t be able to quit Installer without restarting.

  • Flags— Select any of the following options:

    • Relocatable— Allows the user to select where to install the software. Only use this option if the files being installed can be moved from their intended location and if all the files go into one location.

    • Root Volume Only— Installer will allow installation onto the volume from which the system is running. Use this option sparingly, as it will prohibit the installation of this package with NetInstall.

    • Follow Symbolic Links— If the path to an item to be installed contains a symbolic link and this option is selected, the path will be followed with the link. Otherwise, Installer will replace the symbolic link with a folder. In general, this option should be selected unless you know that you want Installer to replace any symbolic links with folders.

    • Overwrite Directory Permissions— Selecting this option will direct Installer to change the permissions on existing folders to match those specified in the package. Use this option with caution, as it can cause unexpected system behavior if permissions are set incorrectly on system folders. Note that this option doesn’t address ownership, only permissions.

    • Allow Revert To Previous Version— Allows Installer to revert to an earlier version of the package.

    • Update Installed Languages Only— Only languages that are currently installed will be updated.

Taking Advantage of Third-Party Utilities

Numerous third-party utilities exist to make package creation easier. There are utilities that cover every aspect of package creation.


logGen is a command-line utility that you can easily use to display files that were modified on your system. For example, you can compare file checksum values before and after an install so that you’ll know what files need to be included in your package. More information is available at the LSA Mac OS X Software site (

Iceberg and Composer

These applications provide alternatives to Apple’s PackageMaker. Although they simplify many tasks of package creation, you’ll want to carefully evaluate which of the three applications is the best fit for your project. Composer, from JAMF Software, can be found at, and Iceberg is available from White Box at The Iceberg application looks similar to PackageMaker and allows for many of the same options, plus a few more.


Pacifist, from CharlesSoft (, provides a friendly graphical package inspector. This handy tool provides a quick Finder–like view of the files contained in the payload of a package. That’s useful when building packages because it provides a quick way to visually inspect the results of your package building, but it can also be used to extract individual files from a package without installing the entire package. The following figure shows a package and all its contents in a Pacifist window displayed in a Finder–like interface.

  • + Share This
  • 🔖 Save To Your Account