C H A P T E R 1 5

Files

This chapter contains guidelines for installing applications—including where to locate application-support files and user-created files—and handling filename extensions.

Installing Files

Installing your software is the first task users must accomplish before they can use your application, and you should ensure that it is a quick and painless experience. The best method is a simple drag install: The user drags an icon or a folder from your CD, for example, to a chosen destination on another disk. The easiest way to achieve such a process is to create an application bundle (for more information, see Inside Mac OS X: System Overview, available on the Mac OS X developer documentation website). If files need to be installed in various locations, you’ll need to create an installer; follow the guidelines described in this section.

If components of your application must be installed in locations that require authentication, you should use Package Maker, the Mac OS X application for creating installation packages (available on the Mac OS X Developer Tools CD).

For an update to an already-installed application, you should provide an installer that modifies only the files required for the new version. Remember that files may have been renamed or moved; don’t look only in the Applications folders, and don’t rely exclusively on filenames to identify your application files; check for creation and modification dates, version numbers, file size, and so on to uniquely identify

C H A P T E R 1 5

Files

your application. If you detect multiple versions of your application, provide information such as the location and creation date of each, and let the user choose which one to update.

If users can download your application from the Internet, help simplify the installation process by making it a disk image. Make sure to clean up after a successful installation by moving unneeded files to the Trash.

When designing your product’s installation procedure, keep the following guidelines in mind:

■Before installing anything, your installer should check the destination volume for previously installed application components. When searching for files, follow the guidelines described previously for software updates.

■Always provide users with a simple default install (an “Easy Install”). Most products should also provide a custom install; if a user has accidentally thrown away a particular file, for example, he should be able to restore it without having to reinstall the whole application.

■Always let users choose a specific folder (or the Desktop) as the installation destination. Don’t require your application to be installed in a particular location.

■Install files only in the locations recommended in “Where to Put Files”

(page 247). If users want to delete your application for some reason, most users will simply drag its icon to the Trash; avoid littering the user’s hard disk with remnant files. If your product uses an installer, it should include an uninstall option that lets the user delete all associated files.

■Advise users about data that might be overwritten during the installation and provide a way for them to back it up first. Don’t overwrite previous user preferences; deal with version and format differences the first time the user opens the updated application.

■Provide choices and explain their impact. For example, one installation option could result in faster performance but consume more disk space; another might use less space but result in slower performance.

■Provide help where appropriate. For example, in a custom install pane, clicking a More Info button should help the user understand why she would want to install the component and the consequences of not installing it. Make dependencies between components clear, but don’t force the user to install anything, even recommended files.

246Installing Files

Apple Computer, Inc. June 2002

C H A P T E R 1 5

Files

■Don’t uninstall Apple system software.

■If your application installs Apple system software—such as QuickTime, CarbonLib, or Help Viewer—make sure the version you install is newer than any version the user already has; otherwise, don’t install it. Make it clear to users which version they already have and which version your application needs, and provide an option for skipping installation of those items.

■During installation, indicate progress, such as the current stage and the time remaining. (See “Feedback and Communication” (page 29).)

■Provide a Cancel or Stop button; if cancelling the installation would compromise the system’s stability, disable the button during those times. If a user cancels an installation, leave the destination disk in the same state it was in before the install (in other words, delete any files installed before the process was cancelled).

■Consider performing your installation the first time the user opens the application, rather than when the user copies the program. This technique is especially well suited for children’s games.

■Consider your application’s audience. It’s likely, for example, that elementary school children install their own games, so tailor your instructions for them (don’t use confusing or technical terms like directory) and make installation as easy as possible for that audience.

Where to Put Files

Mac OS X creates a suite of directories for each new user account. This structure is provided to assist users in organizing related types of files, maintain a default location for task-specific applications (such as iMovie), and facilitate transferring files to and from iDisks.

There are eight predefined top-level user directories. With the exception of certain subdirectories in the user’s home directory (Desktop and Library), users can move or delete these directories.

The Library folder in the user’s home directory contains system or application-support files. Within the Library directory is an Application Support directory, in which you can create a developer-specific or application-specific

Apple Computer, Inc. June 2002

C H A P T E R 1 5

Files

directory to contain all files such as document templates, databases, user preferences, nonsystem fonts, product licenses, and plug-ins (see “Handling Plug-ins” (page 249)). You may want your application to provide its own interface for accessing and managing the contents of this directory.

Three of the predefined folders in the user’s home directory support basic system functionality:

■Desktop: Contains all files visible on the desktop when the user logs in. By default, the contents aren’t visible to other accounts. This directory is the default location for files downloaded with a Web browser (the user can change the location in Internet preferences).

■Public: Allows the user to share files with local and remote users. By default, the contents are visible to other user accounts. This directory contains a drop box, where others can put files for the owner that aren’t visible to other users.

■Sites: Allows users to host a website. When the user turns on Web Sharing (in Sharing preferences), other users can access Web pages in this folder. A sample Web page is provided in this directory.

The remaining directories are intended to provide default locations for storing files. They are not intended to contain files whose primary access is through the application. For example, AppleWorks templates and iTunes music databases should go in the Library directory. The provided directories are the following:

■Documents: The default for storing user-created files not better served by the other directories. Examples include AppleWorks text or spreadsheet documents and TextEdit documents. Don’t put application support files—including user preference settings—here; put them in the user’s Library directory.

■Movies: The default for storing moving images created by the user or exchanged with other users. Examples include QuickTime Player files, iMovie projects, and imported digital video sequences.

■Music: The default for storing music, sound, or MIDI files created by the user or exchanged with other users. Applications that generate music or sound-related files should use this directory as the default storage location. Examples include iTunes user playlists and converted MP3 files.

■Pictures: The default for storing still images created by the user or exchanged with other users—images downloaded from a digital camera, for example.

When a user saves a file to a destination other than the default directory, your application should keep the user’s selection as the default location for saving files.

248Where to Put Files

Apple Computer, Inc. June 2002