mac.column.ted: A Leopard Surprise (Flat) Package

Ted Landau

June 2008

If you've spent time peeking under the hood of Mac OS X, you already know about packages. What you may not know is that Leopard (Mac OS X 10.5) offers a new type of package called a flat package.

Packages are Apple's name for what are essentially folders disguised as single files in the Finder. The two most common uses of packages are for applications and installer documents. Applications (with their often hidden .app extensions) are packages/folders, with the "real" application code as well as a collection of related resources contained inside. Similarly, installer documents (with their .pkg, for package, extension) are packages/folders that contain the files to be installed by the "document" plus the instructions needed to perform the installation correctly.

Overall, packages have functioned very well in Mac OS X. By creating the illusion of a single file, packages make sure that no files are unintentionally left behind when copying or moving the folder/package. The package concept also prevents novice users from easy access to the contents, thereby minimizing the chance that users will "experiment" with the files within and cause unintended trouble. Finally, packages maintain a degree of simplicity by facilitating application resources to reside in a single location, rather than spread out in numerous Library folders (although it is not 100% successful in this regard, as there are Library folders, such as Application Support, where such resources are stored).

Despite all of this shrouding of package contents, if you want to open up a package and examine its contents, it's quite easy to do. Simply access the contextual menu (or Action menu, from a Finder window's toolbar) for the desired package item and select the "Show Package Contents" command.

Unless you are a developer, you won't have much need to delve inside packages. However, packages hold potential rewards even for "common" end users. For example, in application packages, you can change the text of dialog boxes (often more fun than practical), modify menus and edit icons. For installer packages, you can examine exactly what files the package will install and where they will go; you may even be able to make a change that permits an installation to proceed that would otherwise be blocked (circumventing occasional cases where the Installer inappropriately claims that the package is not intended for your Mac hardware or OS X version).

Packages work so well and with so little trouble, there would seem no reason for Apple to mess with them. But mess with them they did. And so, with Leopard, we see the arrival of the flat package.

From an end user's perspective, a flat package is one that has been created in such a way that it acts even more like a single file than an ordinary package. In particular, if you select the contextual menu for a flat package, the Show Package Contents command does not show up! There is no longer a direct and simple way to open a flat package in the Finder.

Flat packages have been used only sparingly in Leopard. They crop up in some (but far from all!) installer packages. They are not used for any application packages.

Why did Apple add flat packages to Leopard? Maybe I missed the memo, but I have never read any explanation. Perhaps Apple wanted to make it even more difficult for users to access the contents of installer packages. Perhaps. But then why are some Apple updates flat packages (such as the Time Machine and AirPort Updates v1.0, released in March) while others are not (such as the AirPort Utility 5.3.2 for Leopard, released more recently in June)? I don't know.

How to open a flat package

Regardless of the rationale behind flat packages (and here we finally get to the main point of this column!), if you do want to peer inside one, you can still do so. In fact, you have at least three options:

• PackageMaker. If you've installed Apple's Developer software, check the /Developer/Applications/Utilities folder for a program named PackageMaker. If you launch it and access its Edit menu, you'll find a command called Launch Flat Package Editor. If you select this command, a separate application opens. From the Open dialog of this application, you can choose a flat package and "open" it.
  
  Once open, you'll see a list of the package's contents. Dig a bit deeper and you can glean some more useful information. For example, click on the Bom item and then select Info from the toolbar ? followed by Preview from the pop-up menu in the window that appears. The result will be a list of all the folders and files (as seen in the figure) that will be modified if and when you install the update.
  
  
  By the way, Flat Package Editor is itself inside a package: the PackageMaker application package. To see it, use Show Package Contents for PackageMaker and navigate to Contents > Resources.
  
  
• pkgutil. You can access the contents of a flat package by using a Unix command called pkgutil. To do so, launch Terminal and type:
  pkgutil --expand {path of flat package} {path of expanded flat package}

For example, for the Time Machine update noted above, and assuming the package is on your Desktop, you could enter:
  pkgutil --expand ~/Desktop/Time-Machine-Update.pkg ~/Desktop/Time-Machine-Update-expanded.pkg

This creates a new package file (with "expanded" in its name) that contains the same data as the original flat package, but behaves as a standard package. That is, back in the Finder, you can open the expanded package via the Show Package Contents command.
  
  If you use the command to open an expanded package, there may yet be another package inside that you can similarly open. Upon doing this, you'll discover that flat packages have a different structure than standard packages. For starters, the top-level Contents folder is gone. Also, the Archive.pax.gz file (where the to-be-installed updated files are stored) is gone, replaced by a file called Payload.
  
  A Payload file is an archive. To access its contents, just double-click the file. Archive Utility (an application located in /System/Library/CoreServices) launches and decompresses/unarchives the file. You'll now see a Payload 2 2 folder; inside this folder are the actual to-be-installed files.
  
  There are numerous other actions you can perform with the pkgutil command. You can read the full documentation here. One interesting option is to run yet another command called repair-packages. According to its documentation, repair-packages is what Disk Utility uses when you select to Verify or Repair Permissions.
  
  
• Pacifist. A third and final option is to use the third-party utility Pacifist. The latest version of this wonderful utility works with flat packages as well as standard ones. Using its Package Contents button (as seen in the figure), you can view the expanded contents of the Payload file (similar to what you see when you open the Payload 2 2 folder, as described in the previous section). Using the Resources button, you view a list of items in the package itself (essentially the same as the list of files seen via Apple's Flat Package Editor).
  
  

[Note: This column continues my look, started in last month's column, at some of the lesser known and more technical new features in Leopard.]

To send comments regarding this column directly to Ted, click here. To get Ted's latest book, Take Control of Your iPhone, click the link.

Resources