Important: The information in this document is obsolete and should not be used for new development.
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
.
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
Currently, the typical user-experience for Mac OS X software installation looks something like the following:
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.
The browser launches StuffIt Expander to expand the downloaded file. The user watches a progress bar.
StuffIt Expander launches Disk Copy to mount the disk image. The user watches another progress bar.
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.
The user unmounts the disk image.
The user throws away the .dmg
file.
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:
The user downloads a .dmg
file using a browser.
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.
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.”
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.
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.
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:
Disk Copy mounts the disk image in a hidden location so that it is not displayed on the Desktop or in Finder windows.
After mounting the image, Disk Copy copies the contents of the disk image out of the image and into the same directory in which the .dmg
file is stored, which is usually the user’s download folder. If there is only one file visible to the user in the disk image, that file is copied directly to the destination. Any hidden files, such as a .DS_Store
file or a folder background image, are not copied. If there are multiple files visible to the user at the root of the disk image, a new directory is created at the destination and the visible files are copied into it. If present, the disk image’s .DS_Store
file is also copied to the new directory, thereby preserving icon positions; other hidden files are not copied. The new directory’s name is the same as the disk image’s, but without the .dmg
extension.
After copying the disk image’s contents, Disk Copy unmounts the image, clears the internet-enabled flag in the .dmg
file, and moves the .dmg
file into the Trash. Disk Copy does not delete the .dmg
file. If the user wants to keep the .dmg
file of a download, perhaps for archival purposes, the user can retrieve the file from the Trash. Because Disk Copy has cleared the internet-enabled flag, however, the .dmg
file now behaves like a regular disk image file. In other words, the internet-enabled behavior occurs only when the disk image is initially downloaded.
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:
To ensure optimum launch time for your application, be sure you address possible prebinding issues described in “Drag-and-Drop Installation” and “Prebinding.” In brief, you should provide users with information on why they might need to update prebinding for your application and how to to so.
Some users may be confused when they double-click a disk image file and it then “goes away” (to the Trash).
A user who finds and retrieves the image file from the Trash may again be confused that double-clicking it a second time doesn’t produce the same behavior.
Some users may not be experienced with the use of disk images, whether these images are internet enabled or otherwise.
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.
© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)