How to Create a Disk Image Installer for Apple Mac OS X

Creating a disk image installer (product container) for OS X is pretty easy. Apple's Software Delivery Guide provides a good overview of the basic steps needed to create a disk image. However, there are a few less obvious steps you have to take to make your disk image look as professional as that of Firefox or Skype. Also, we want to make this process scriptable so we can generate the disk image as part of an unattended build system.

I know of two problems in particular:

  • Column view interferes with your layout
  • Source for background image clutters your layout

You may be blissfully unaware of the column view issue, so I recommend that you, at least for the duration of building your disk image, enable Open new windows in column view in Finder > Preferences > General.

While writing this post, I was notified about a new version of Google Notifier. This is what I saw when I opened the installer disk image:

google-notifier-columns.png

I hit Cmd-1 to switch to icon view and that improved the layout:

google-notifier-no-columns.png

Notice that there is white line at the bottom of the window; looks like a status bar will fit there:

google-notifier-statusbar.png

I recommend reading parts of the Software Delivery Guide before reading any further; start no later than Product Containers and stop when you reach Managed Installs. But don't follow the directions on creating a disk image from a folder, as this will make it harder to get the professional look we are going for.

You also need to install Apple's Xcode. It doesn't cost a thing.

Creating a Disk Image Template

First, we want a disk image that we can use as a template in a script or automated build system. Open Disk Utility which you find in the Utilities folder in Applications. Click the new image button, and select a size that is at least twice as much as you ever figure you will need on your disk image. You should select the sparse image format. Carefully select the name of the image, as this will be the name of the directory that will eventually open on your customer's desktop when they open the final disk image. In this example, I will use YoyodyneApp.

When you click on create, a new disk image is created and mounted. You will see that two new items show up in the left column of Disk Utility:

  • YoyodyneApp.sparseimage
    • YoyodyneApp

The first item is the actual disk image, and the second item is a partition within the disk image. When you select the partition, you can see where it is mounted. In my case, the mount point is /Volumes/YoyodyneApp. Notice that the mount point is a link. Click on the link thereby opening the YoyodyneApp directory in a regular finder window with toolbars (and column view if you set the preference as described above):

yoyodyneapp-initial-view.png

This is not how we want to present the installer to the end user. Let's fix that:

  • Open a Terminal window and type:
bless --folder /Volumes/YoyodyneApp \
  --openfolder /Volumes/YoyodyneApp
  • In the Finder window for YoyodyneApp:
    • Click the little pill shaped icon to hide the toolbar.
    • Hit Cmd-1 to switch to icon view.
    • Hit Cmd-E to eject the disk image (important).
  • Switch to Disk Utility
    • Select Yoyodyne.sparseimage.
    • Click open.

yoyodyneapp-blank-canvas.png

Eventually, we want to send a compressed version of the disk image to the end user. During that process, your layout can be lost (due to column view) unless you follow the steps above exactly.

Customizing the Background

Now is the time to brand the installer disk image with a custom background.

Drag your background image to the Finder window for YoyodyneApp. It has to be in the disk image to display properly at the end user's computer.

  • In the Finder window for YoyodyneApp:
    • Hit Cmd-J to open the view options for YoyodyneApp.
    • Make sure you select This window only.
    • Select Picture under Background:
    • Select the background image you just dragged to this folder. (I have to click on Picture once more after selecting the file).
    • You can make other customizations if you like, I prefer setting the icon and text sizes to their maximum values.
  • Open a Terminal window and type (use the actual name of your background image):
/Developer/Tools/SetFile -a V \
  /Volumes/YoyodyneApp/YoyodyneLogo.png

This will hide the background image from Finder. But not until you eject and open the image from Disk Utility. So do that now.

Link to Applications

Apple recommends that you include a symbolic link to /Applications if you expect the user to drag your application there (manual install):

  • Open a Terminal window and type:
ln -s /Applications /Volumes/YoyodyneApp/.
(include the period)

yoyodyne-branded.png

Application Placeholder

The goal is to create a template with our preferred layout. Most of the steps to create this template are manual and not easily scriptable. So we need to create the final layout once and save it as a template we can use in the future as part of an automated build process. Since Mac applications are all saved in a directory with a special bit set, we can create the applications directory so we can finish the layout.

  • In the Finder window for YoyodyneApp:
    • Hit Shift-Cmd-N to create a new folder.
    • Type in the name followed by .app, for example Yoyodyne.app. Finder will hide the extension, but change the icon.

yoyodyne-placeholder.png

Finalizing the Layout

Oops, I created the icons in the wrong order. I prefer having the Applications folder on the right of the application. That is easy to fix:

  • In the Finder window for YoyodyneApp:
    • Move the application icon near the left side of the window.
    • Move the Application folder icon near the right side of the window.
    • Hit Cmd-A to select all the icons.
    • Select Clean Up Selection in the View menu.
    • Move both icons so the are nicely centered.

yoyodyne-aligned.png

I designed an icon for the application:
yoyodyneicon.png

This is PNG file, perhaps you already have an .icns file. The procedure is the same:

  • Open a Terminal window
    • Change directory to the folder where you stored the icon.
    • Type:
sips -i YoyodyneIcon.png
(works on most graphic image files, including .icns files)
open .

This will use the picture/icon found in the file as the icon for that file, and then open the folder.

  • In the Finder window you just opened:
    • Select the icon file.
    • Hit Cmd-I to open an info window.
  • In the info window you just opened:
    • Click on icon next to the file name at the very top of this window (it should get a blue halo).
    • Hit Cmd-C to copy the icon to the clipboard.
  • Go back and select the application placeholder
    • Hit Cmd-I to open an info window.
  • In the info window you just opened:
    • Click on icon next to the file name at the very top of this window (it should get a blue halo).
    • Hit Cmd-V to copy the icon from the clipboard.
  • Close the info windows.

yoyodyne-app-logo.png

Following the same procedure, you can also change the icon of the mounted disk image. Locate it on the desktop and hit Cmd-I to get started:

yoyodyne-disk-icon.png

This concludes the layout part.

Testing the Disk Image Template

Make sure you have ejected the disk image before you proceed.

  • Open a Terminal window
    • Change directory to the folder where you stored the disk image template (YoyodyneApp.sparseimage).
    • Type:
hdiutil convert YoyodyneApp.sparseimage \
  -format UDBZ -o YoyodyneApp.dmg
open YoyodyneApp.dmg

This will open the compressed image. Now carefully examine the new window. The following should be true:

  • Your background art is clearly visible (the window is not in column view).
  • There are no tool- or status-bars.
  • The disk image icon is what you chose.

I also recommend that you copy the .dmg file to a USB stick or similar, and check that it looks right on a co-worker's computer.

At this point you should eject the image and store it in your version control system. Make sure you eject it before you try to store it. Store the .dmg, not the .sparseimage.

Automated Build of Disk Image Installer

The template we made in the previous step should be pretty small, around 42K and can easily be managed by version control software. Let's assume the built application is also under version control. For example, let say we are using subversion, and the .dmg and application are stored as:

  • svn://svn.yoyodyne.com/YoyodyneApp/YoyodyneApp.dmg
  • svn://svn.yoyodyne.com/YoyodyneApp/Yoyodyne.app

Building the disk image installer then becomes as easy as:

svn export \
  svn://svn.yoyodyne.com/YoyodyneApp/YoyodyneApp.dmg
hdiutil convert YoyodyneApp.dmg \
  -format UDSP -o YoyodyneApp
rm YoyodyneApp.dmg
hdiutil mount YoyodyneApp.sparseimage
svn export \
  svn://svn.yoyodyne.com/YoyodyneApp/Yoyodyne.app/Contents \
  /Volumes/YoyodyneApp/Yoyodyne.app/Contents
hdiutil unmount /Volumes/YoyodyneApp
hdiutil convert YoyodyneApp.sparseimage \
  -format UDBZ -o YoyodyneApp.dmg

YoyodyneApp.dmg is now ready to ship to your customers.

12 Responses to “How to Create a Disk Image Installer for Apple Mac OS X”

  1. Halkmund says:

    I had to change “hdutil unmount /Volumes/YoyodyneApp” into “hdutil eject /Volumes/YoyodyneApp” for the script to work. With the unmount verb the convert failed because of the sparseimage resource being temporarily unavailable… (in use by diskarbitrationd).

    The rest all works fine. Nice job.

  2. Geowerker says:

    With Leopard, some changes to Disk Utility complicate the “Creating a Disk Image Template” step. When creating a new image, if you change the ‘Volume Size’ the ‘Partitions’ setting will change. Before you click ‘Create’, ‘Partitions’ should be set to ‘No partitions’. I had problems with other settings (the sparseimage disk name would revert to ‘Disk 1′ after being ejected); may be a Disk Utility bug, but no one should need multiple partitions for an installer anyway.

  3. SciTools says:

    OS X and Understand 2.0…

    Recently we added OS X support for Understand 2.0. I’m not a Mac user myself, but as the “Build Engineer” I’ve spent quite a bit of time on our Mac build machine lately getting the installer polished up and I have……

  4. KevinG says:

    Thanks for the wonderful article – I spent all day trying to do something similar without know much about using macs. Your well written blog quickly helped me create the image I needed.

  5. [...] those looking for technical details on how to make a DMG like this, there are many existing articles that do a great job explaining the process. There is even a video [...]

  6. dgallardo says:

    Excellent article, thanks! Just thought I’d mention that you should test the dmg template on multiple versions of OS X. I created a very tightly spaced one on 10.4. When opened on Leopard, I got an unwanted scroll bar on the side.

  7. Bodo says:

    Thanks for this great article. TV-Browser will have a very nice .dmg because of this :).

  8. DD Poker says:

    Great post (and comments) – very useful building our new mac installer.

  9. Ferdi Koomen says:

    This saved me a huge amount of time. Great article!

  10. [...] How to Create a Disk Image Installer for Apple Mac OS X [...]

  11. [...] Peter Ahe’s Blog was helpful in getting me going on the right direction and understanding what was required to get the disk image installer created. Filed under: Mac Leave a comment Comments (0) Trackbacks (0) ( subscribe to comments on this post ) [...]

  12. anonymous says:

    SetFile requires the Developer Tools to be installed. On any Mac you can just use:

    chflags hidden /path/to/file
    chflags nohidden /path/to/file

    to make a file hidden or visible.

Leave a Reply