< Previous PageNext Page > Hide TOC

Legacy Documentclose button

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


Distributing Software With Internet-Enabled Disk Images

Disk images have become the preferred transport mechanism for downloading files in Mac OS X. Starting with Mac OS X version 10.2.3, the Disk Copy application (located in /Applications/Utilities) supports “internet-enabled” disk images, which help create a better user experience when installing from disk images. This section describes that process and how you can take advantage of it.

Note: Starting in Mac OS X version 10.3, the features of the Disk Copy application were integrated into the Disk Utility application, also located in /Applications/Utilities.

Contents:

Improving the User Experience
Creating An Internet-Enabled Disk Image
Adding a License Agreement to a Disk Image
How Disk Copy Handles an Internet-Enabled Disk Image
Caveats for Internet-Enabled Disk Images


Improving the User Experience

Currently, the typical user-experience for Mac OS X software installation looks something like the following:

  1. The user uses a browser to download a disk image file (a file with a .dmg extension) that has been archived in Stuffit or MacBinary format.

  2. The browser launches StuffIt Expander to expand the downloaded file. The user watches a progress bar.

  3. StuffIt Expander launches Disk Copy to mount the disk image. The user watches another progress bar.

  4. The user locates the mounted image, opens a Finder window (if one isn’t set to open automatically), and copies the contents out of the disk image.

  5. The user unmounts the disk image.

  6. The user throws away the .dmg file.

  7. The user throws away the compressed .dmg file, if StuffIt Expander is not configured to delete compressed files automatically.

However, it is now possible to eliminate many of these steps. Because read-only .dmg files use a flat file format and Disk Copy can create compressed disk images, it is unnecessary to convert a .dmg file to either StuffIt format or MacBinary format. As a result, steps 2 and 7 can be eliminated. New internet-enabled disk images eliminate most of the remaining steps, and the user experience is simplified as follows:

  1. The user downloads a .dmg file using a browser.

  2. The browser launches Disk Copy with the .dmg file. The user watches a progress bar while Disk Copy mounts the disk image, copies the contents out of the image, unmounts the image, and moves the .dmg file to the Trash.

  3. The user locates the downloaded files and perhaps moves them to their final destination.

In the new model, the user never needs to handle or see the .dmg file or the mounted disk image. Instead, the user sees only the files contained within the disk image. In other words, the .dmg file becomes an implementation detail that is transparent and irrelevant to the user; the included files appear at the download location as if they were downloaded directly.

When it moves the .dmg file to the trash, Disk Copy clears the internet-enabled flag, so that if the user decides to remove the file from the trash for future use, it will operate as a standard disk image.

Note: If necessary, you can use PackageMaker to package your software, then distribute the package via internet-enabled disk image. After receiving the software, the user must install it with Installer (and delete the package file, if they don’t want to keep it around). For information on when you might want to do this, see “Reasons for Using PackageMaker and Installer.”

Creating An Internet-Enabled Disk Image

An internet-enabled disk image is identical to a regular disk image except that it has a special flag set. You create the disk image normally and then set the internet-enabled flag with the following command, executed in a Terminal window, where <pathToDmg> is the path to the image file:

hdiutil internet-enable -yes|-no|-query <pathToDMG>

Use -yes to enable the flag, -no to disable the flag, and -query to test whether the .dmg file is already internet-enabled.

You can set the internet-enabled flag only for read-only disk images. Read-write disk images cannot be internet enabled. Older .img and .smi files also cannot be internet enabled.

Disk Copy clears the internet-enabled flag after it processes a disk image. For this reason, if you need to test the file before putting it online, you must make a copy of the disk image first and test the copy. You cannot retrieve a processed disk image from the Trash and then place it online—it will no longer be internet-enabled.

The internet-enabled flag does not interfere with previous versions of Disk Copy. Previous versions of Disk Copy will simply ignore the flag and treat the disk image as it would a non-internet-enabled disk image.

Note: For a brief tutorial on creating a disk image, see Porting UNIX/Linux Applications to Mac OS X in Darwin Documentation.

Adding a License Agreement to a Disk Image

The Disk Copy application has the ability to display a multi-lingual software license agreement before mounting a disk image. The image will not be mounted unless the user indicates agreement with the license. You can obtain a software development kit (Software License Agreements for UDIFs) that explains how to add license agreements to Mac OS X-native UDIF disk images at http://developer.apple.com/sdk/index.html.

How Disk Copy Handles an Internet-Enabled Disk Image

Disk Copy processes an internet-enabled disk image a little differently than a regular disk image, although the differences are mostly additional behavior. The disk image can still contain a software license agreement or it can be encrypted and require a password. The following are the new and modified Disk Copy behaviors when handling an internet-enabled disk image:

Caveats for Internet-Enabled Disk Images

Although supplying an internet-enabled disk image can reduce the number of steps a user has to perform to install your software, there are some issues you should be aware of:

If you are concerned about any of these issues, you can provide instruction at your download site or through a Read Me file or other mechanism. You can tailor the information you provide to the sophistication of your target audience.



< Previous PageNext Page > Hide TOC


© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.