< Previous PageNext Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Software Distribution Guidelines

This section provides a brief description of how to distribute Mac OS X software, and of the two primary mechanisms for installing it: drag-and-drop installation, which allows a user to simply drag the software to the appropriate folder; and package installation, which provides a more sophisticated set of installation options. It also lists benefits of working with PackageMaker and Installer, the native applications for package-based installation in Mac OS X.

Getting Software to the User

Whether your software can simply be dragged to the desired location or requires an installation process, you must first get the software to the user. Most software for Mac OS X is distributed on CD or by Internet downloads, which are often supplied as compressed disk images, or as archived files in various other formats.

For software that stores data or code in the resource fork of a file, the distribution mechanism must ensure that such data or code is not lost in transfer. This is especially likely to be a problem when files can be moved between different file systems. One solution is to distribute your software in an archived format (such as a Stuffit archive file) that prevents modification of the contents during transfer, and to have a user expand it on the target volume. This has the advantage of preserving data stored in resource forks—for related information, see “Preserving Resource Fork Data.”

System administrators in business and education environments may need to distribute and install site-licensed software from a central location. Apple Remote Desktop provides an ideal solution for this situation. For more information, see http://www.apple.com/remotedesktop/.

A disk image is a special kind of file that the Finder can mount as it would any disk. Mac OS X provides the Disk Utility application (located in /Applications/Utilities) for creating and mounting disk images. (Prior to Mac OS X version 10.3, there is also a separate Disk Copy application.) Disk image files typically have an extension of img, dmg, or smi. They can optionally be compressed, and can also be encrypted, requiring a password or phrase before mounting. For more information on working with disk images, use choose Help > Disk Utility Help in the DiskUtility application. For a brief tutorial on creating a disk image, see Porting UNIX/Linux Applications to Mac OS X in Darwin Documentation.

Note: You can also use the command-line tool hdiutil to work with disk images. For more information, see the man page for that tool.

Installing software from a downloaded disk image generally requires a number of steps before the actual installation can take place, followed by deleting the leftover files. Starting with Mac OS X version 10.2.3, the Disk Copy/Disk Utility application supports “internet-enabled” disk images, which can reduce the number of steps and improve the user experience. This mechanism is described in “Distributing Software With Internet-Enabled Disk Images.”

Note: You may want to use tools such as tar and gzip to distribute certain software, such as command-line tools. If so, refer to the man pages for those tools or to other UNIX documentation.

Drag-and-Drop Installation

Because most applications for Mac OS X are built as self-contained application bundles (defined below), users can install them in most situations just by dragging the bundle to a folder for which they have write permission. This drag-and-drop type of installation is the preferred method for installing Mac OS X software. For software of this type, you can provide simple installation instructions in a brief online or printed document.

One complication of using drag-and-drop installation is that it does not automatically support updating of prebinding. Prebinding is a process that can improve the user experience by providing a faster application launch. For more information on working with prebinding, see “Prebinding.”

An application bundle is a directory in the file system that stores executable code for an application and the software resources related to that code. An application bundle ends with the extension .app and is presented to the user by the Finder as a single file, with the extension hidden. Double-clicking the file launches the application executable, which is stored in a directory within the bundle (for example, see the MyApp executable in Listing 1). Bundles may even contain multiple executable files for different environments.

An application bundle can include localizations, and applications can automatically display a set of localized resources (including the application name itself) that matches a user’s Languages preference.

Plug-ins and frameworks are also types of bundles, though frameworks are not presented by the Finder as a single file.

Note: You can examine the contents of a bundle in the Finder by Control-clicking it and choosing Show Package Contents from the contextual menu. In a Terminal window, you can display a bundle’s contents with the find command. The Terminal application is available in /Applications/Utilities.

Listing 1 shows a partial layout for the application bundle for the application MyApp. Items preceded by a dash represent directories. The three directories English.lproj, French.lproj, and Japanese.lproj store language-specific resources for, respectively, U.S. English, French, and Japanese.

Listing 1 A partial bundle layout for a complex application

- MyApp.app

    - Contents

        - MacOS

            MyApp

          Info.plist

          PkgInfo

        - Resources

              Hand.tiff

              WaterSounds

            - English.lproj

                 house.jpg

                 InfoPlist.strings

                 Localizable.strings

                 CitySounds

            - French.lproj

                 house.jpg

                 InfoPlist.strings

                 Localizable.strings

                 CitySounds

            - Japanese.lproj

                 house.jpg

                 InfoPlist.strings

                 Localizable.strings

                 CitySounds

Because an application keeps everything it needs within its bundle, simple drag-and-drop installation reduces file-system clutter and eliminates dependencies on items residing elsewhere in the file system. It also gives users the option of not copying items to their hard disks that they are not particularly interested in (such as Read Me files). To uninstall an application, all users have to do is remove the application bundle from the volume.

Package-Based Installation

For some software, simple drag-and-drop installation is not sufficient. When the requirements for preparing an application for execution are more complex, you can put your software into a package, distribute it through any convenient means, and let users install it with an installer application.

This is the approach supported by PackageMaker and Installer, the native applications for package-based installation in Mac OS X. You use PackageMaker to create an installation package that contains all the information and resources required to install your software. When a user double-clicks the package file, Installer (included in every Mac OS X installation) is launched to handle the actual installation.

Note: This document does not describe third-party or open-source packaging and installation mechanisms.

“Reasons for Using PackageMaker and Installer” lists some of the advantages of this type of installation. Information on using PackageMaker and Installer is found throughout this document—for an introduction, see “A Quick Look at PackageMaker and Installer.”

Reasons for Using PackageMaker and Installer

At the highest level, using PackageMaker and Installer to install your software provides these options:

a professional-looking presentation, customized to your particular software
an installation process that is easy for unsophisticated users
support for upgrading your software, which may require replacing only certain files
support for custom installation (so that a user can choose to install part or all of the packaged software)
the ability to ensure correct prebinding (a mechanism to provide faster application launching, described in “Prebinding”)

On a more detailed level, PackageMaker and Installer provide fine control over the installation process, including

the ability to provide a Welcome page, Read Me page, and custom background image
the ability to perform operations before installing, such as
- requiring the user to agree to a license
- requiring the user to authenticate before installing in a privileged location
- checking for the presence of required hardware or other features
control over details such as whether an installation
- allows the user to specify a destination for the software or requires a specific destination
- recommends or requires a restart, logout, or shutdown after completion
- uses the file ownership and permissions of the user installing the software or of the packaged software itself

For a detailed description of the available features, see “PackageMaker and Installer Features,” as well as PackageMaker Help.