TweetFollow Us on Twitter

Ship It! Distributing Your Software, Part 2

Volume Number: 20 (2004)
Issue Number: 2
Column Tag: Programming

Mac OS X Programming Secrets

by Scott Knaster

Ship It! Distributing Your Software, Part 2

In our last thrilling installment (or was it a thrilling installation?), we discussed the simplest method of distribution for your Mac OS X software: disk images. We talked about using Disk Copy or Disk Utility to make a disk image, and we described the relatively recent technology of Internet-enabling a disk image so that it cleans up after itself when users download it in Safari.

When you distribute software on a disk image, there is no actual installing taking place. Users simply drag and drop files onto their hard disks. That's the great strength and weakness of disk images: they're easy for you to make and easy for users to figure out, but you can quickly run into their limitations. For example, what if you need to make sure files end up in specific places on the disk? What about checking the progress of the installation and taking some action based on what's happening? Most commercial applications need to do things like this when they're installed. For more control of the installation process, Apple provides the PackageMaker and Installer tools.

Meet Your Maker

PackageMaker is an application that comes with Mac OS X. You use PackageMaker to create packages, which are documents with extension .pkg that contain files to be installed and related files used during the installation. An Apple application called Installer reads the information from a package and performs the installation.

The two biggest tricks PackageMaker installations can do that disk images can't are installing files anywhere in the system, and running scripts while the installation is happening. To install files where you want them, you'll create a directory structure in your package that shows how you want files installed in the system, and includes a few extra items used by the installation itself. In order to run scripts, Installer defines certain events in the installation process and looks for scripts with names corresponding to those events. If the scripts exist, Installer runs them.

Let's take a deeper look at setting up your files and scripts for installation. Please gaze directly into the magazine.

Everything in its right place

You'll make a set of directories and files that indicates where you want everything to end up after the installation. The basic pieces of the directory structure are as follows:

  • You'll create a directory that contains all the other directories and files in the package. This directory can have any name, such as "PackageContents" or "Fred". When you run PackageMaker, you locate this folder.

  • Within the all-enclosing directory, you'll have a directory that holds various files used for installation, such as install-time scripts, the license and readme docs, and so on. Again, this directory can have any name - you specify it in PackageMaker.

  • A second directory inside the outermost directory holds the files to be installed. They're arranged in directories according to the way you want them to be installed. When you run PackageMaker, you specify whether you the files can be installed anywhere or must be placed in absolute locations in the system.

Here's an example. Let's say we're going to install a package that consists of a music application, 3 system sounds, and a screen saver module. Our package directory structure would look like this:

PackageContents
   PackageRoot
      Applications
         Music2MyEars
      System
         Library
            Sounds
               sound1.aiff
               sound2.aiff
               sound3.aiff
            Screen Savers
               ears.saver
   PackageResources
      License.rtf
      ReadMe.rtf
      preflight
      preinstall
      postinstall 
      postflight

The files in the PackageRoot directory are the software itself. We want the files installed in specific locations. When we run PackageMaker to create the package, we can make sure that will happen.

The PackageResources directory is filled with files that will be used during the installation. These include the ReadMe and license documents, along with several scripts (preflight, preinstall, etc.) that Installer will run. In this example, our text files are RTF, but you can also use .txt or .html files.

Staying in Control

When the user runs Installer, usually by double-clicking a .pkg file, these are the steps that take place:

  • Installer looks in the package for an InstallationCheck script and runs it, if it's there. This script provides an opportunity to cancel the installation by returning a nonzero value.

  • If there's a Welcome file (such as Welcome.rtf or Welcome.html), Installer displays it. Otherwise, a default Welcome screen appears. If there's a background image (a file named "background" with extension .tiff, .jpg, .gif, .pdf, or .eps), it's displayed behind the Welcome.

  • If there's a ReadMe file (such as ReadMe.rtf or ReadMe.html), it's displayed next.

  • Next, the License file is displayed.

  • When the user gets to the Select a Destination screen, Installer runs the VolumeCheck script (if it exists) for each mounted volume. VolumeCheck can return a nonzero value to prevent a volume from being eligible for installation.

  • After the user clicks Install, the preflight script is run. Like the other scripts, preflight can cancel the installation by returning a nonzero value.

  • If the user is upgrading the package from a previous version, Installer runs the preupgrade script. Otherwise, preinstall is run.

  • The package contents are copied to the destination. Actual installing, wow!

  • If this was an upgrade, the postupgrade script is run. Otherwise, postinstall is run. There's still time to cancel the installation, which happens if these scripts return nonzero.

Installer runs the postflight script, if it's present.

As you can see from these steps, you have a chance to check the installation with many different scripts: InstallationCheck and VolumeCheck, preflight, preinstall or preupgrade, postinstall or postupgrade, and postflight. You should specify a shell in the first line of your script, using the !#/bin/sh convention. Installer provides a bunch of arguments and environment variables you can use in the scripts. For example, the first argument ($1) is the full path to the installation package, $2 is the path to the destination, and $3 is the mountpoint of the destination volume.

Pack it Up

Once you have written the scripts you want, created the ReadMe and related files, and assembled everything in the right directories with your installation files, it's time to make the package itself. You do this by running PackageMaker, which is located in Developer/Applications/Utilities/. When you run PackageMaker, you see the lovely screen that appears in Figure 1. It's safe to say Jonathan Ive hasn't gotten hold of this one yet.


Figure 1. This is the screen that appears when you launch PackageMaker. It's not very pretty, but it works just fine.

To start assembling your package, fill out the fields on the Description tab. The Title and Description fields provide a place for information that's visible to users when the Installer is running. Click the Files tab to specify the source location of the files to be installed. In our example above, this is the PackageRoot directory. Just to be macho, note that the field for the directory is editable text, so if you're really geeky and you hate clicking through a file dialog, you can actually type the directory path yourself.

Next, use the Resources tab to specify where the scripts, ReadMe, and similar files are located. In our earlier example, this was the PackageResources directory.

The Info tab provides a few interesting options. For example, you can choose whether to recommend or require a restart here. Restarting is mean and should be avoided whenever possible. (In Panther, you can also specify that logout is required, but you can't do it here: you have to modify the Info.plist to do so. To make this happen, add an "IFPkgFlagRestartAction" key with a value of "RequiredLogout" to the package's Info.plist.) If your software doesn't have to be installed in a particular location, check the Relocatable box and users will get to pick where your software should go. The last tab, Version, lets you specify info that appears in the Finder.

When you have your package just the way you want, you should save in PackageMaker, then choose File * Create Package to make the package. When you double-click the package, Installer will launch and you'll get the exciting display you see in Figure 2.


Figure 2. The Installer opening screen can display custom text and background image.

There are a few more Installer features that aren't available in PackageMaker. Instead, you have to edit the package's Info.plist file to get them. For example, when you include a background image in your package, Installer stretches it out to fill the entire window, which is ugly if the image has the wrong proportions. You can gain more control over how the image is used by editing the Info.plist file with Property List Editor.

In the package shown in Figure 2, the Info.plist file has two new keys added to it: IFPkgFlagBackgroundScaling and IFPkgFlagBackgroundAlignment, to make sure that that bee and that guy don't take over the screen. The first key, which controls how the image is scaled, is set to "none". You can also use "tofit" (the default) and "proportional". The second key, for alignment, is set to "bottomleft". Other valid alignments are "left", "right", "top", "bottom", "center" (the default), "topleft", "topright", and "bottomright".

PackageMaker has a few more tricks, such as the ability to create metapackages, which are packages that contain and install other packages. Metapackages can present and sort through complex sets of dependencies for installing software. Another cool feature is the ability to install packages across a network, which you can do if you have Apple Remote Desktop.

Installermania

PackageMaker isn't the last word in installers. Lots of commercial software requires more control than you can get from PackageMaker and Installer. The best-known non-Apple installer packages are made by MindVision Software (InstallerVise, ViseX, and FileStorm), and Aladdin (StuffIt InstallerMaker). These applications let you do things that are beyond PackageMaker, such as creating installs that work on OS 9 or Windows, displaying multiple "tips" screens during install, and automatically adding items to the OS X dock. These products compete with free software from Apple, so they have to be feature-packed.

You can find out more, or even download whole manuals and applications, by visiting the web sites at www.mindvision.com and www.stuffit.com/mac/installermaker/. MindVision downloads are fully functional, with limits on the installers you build until you buy a registration key. The InstallerMaker download is fully functional, but produces installers that say you're using an unregistered copy.

Speaking of free stuff, Apple provides a pile of fine documentation on packages, PackageMaker, and related topics. For much more detail on the stuff we talked about in this article, check out the following URL:

http://developer.apple.com/documentation/DeveloperTools/Conceptual/SoftwareDistribution.

Have fun getting your installer together. Remember, no matter how hard you work on your application, nobody will be able to use it unless you produce an installer, disk image, or other trick to get it out into the world.


Scott Knaster has been playing with Apple computers, and occasionally working with them, since 1977. Wow, that's a long time! Scott has written books and articles for normal human beings as well as programmers. Photo of Scott and his friend Jollibee courtesy of John Vink Photography.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

HandBrake 1.0.2 - Versatile video encode...
HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs. Features Supported Sources VIDEO_TS folder, DVD image or real DVD (unencrypted... Read more
PhotoDesk 4.1.5 - Instagram client for p...
PhotoDesk lets you view, like, comment, and download Instagram pictures/videos. (NO Uploads! / Image Posting! Instagram forbids that! AND you need an existing Instagram account). But you can do so... Read more
Sound Studio 4.8.6 - Robust audio record...
Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
Capo 3.5.1 - Slow down and learn to play...
Capo lets you slow down your favorite songs so you can hear the notes and learn how they are played. With Capo, you can quickly tab out your songs atop a highly-detailed OpenCL-powered spectrogram... Read more
Google Earth 7.1.8.3036 - View and contr...
Google Earth gives you a wealth of imagery and geographic information. Explore destinations like Maui and Paris, or browse content from Wikipedia, National Geographic, and more. Google Earth combines... Read more
QuickBooks 16.1.11.1556 R12 - Financial...
QuickBooks helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save. Built for... Read more
Google Earth 7.1.8.3036 - View and contr...
Google Earth gives you a wealth of imagery and geographic information. Explore destinations like Maui and Paris, or browse content from Wikipedia, National Geographic, and more. Google Earth combines... Read more
QuickBooks 16.1.11.1556 R12 - Financial...
QuickBooks helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save. Built for... Read more
FileZilla 3.24.0 - Fast and reliable FTP...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.24.0: New The context menu for remote file search... Read more
Bookends 12.7.8 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more

Super Mario Run dashes onto Android in M...
Super Mario Run was one of the biggest mobile launches in 2016 before it was met with a lukewarm response by many. While the game itself plays a treat, it's pretty hard to swallow the steep price for the full game. With that said, Android users... | Read more »
WarFriends Beginner's Guide: How to...
Chillingo's new game, WarFriends, is finally available world wide, and so far it's a refreshing change from common mobile game trends. The game's a mix of tower defense, third person shooter, and collectible card game. There's a lot to unpack here... | Read more »
Super Gridland (Entertainment)
Super Gridland 1.0 Device: iOS Universal Category: Entertainment Price: $1.99, Version: 1.0 (iTunes) Description: Match. Build. Survive. "exquisitely tuned" - Rock Paper Shotgun No in-app purches, and no ads! | Read more »
Red's Kingdom (Games)
Red's Kingdom 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Mad King Mac has kidnapped your father and stolen your golden nut! Solve puzzles and battle goons as you explore and battle your... | Read more »
Turbo League Guide: How to tame the cont...
| Read more »
Fire Emblem: Heroes coming to Google Pla...
Nintendo gave us our first look at Fire Emblem: Heroes, the upcoming mobile Fire Emblem game the company hinted at last year. Revealed at the Fire Emblem Direct event held today, the game will condense the series' tactical RPG combat into bite-... | Read more »
ReSlice (Music)
ReSlice 1.0 Device: iOS Universal Category: Music Price: $9.99, Version: 1.0 (iTunes) Description: Audio Slice Machine Slice your audio samples with ReSlice and create flexible musical atoms which can be triggered by MIDI notes or... | Read more »
Stickman Surfer rides in with the tide t...
Stickson is back and this time he's taken up yet another extreme sport - surfing. Stickman Surfer is out this Thursday on both iOS and Android, so if you've been following the other Stickman adventures, you might be interested in picking this one... | Read more »
Z-Exemplar (Games)
Z-Exemplar 1.4 Device: iOS Universal Category: Games Price: $3.99, Version: 1.4 (iTunes) Description: | Read more »
5 dastardly difficult roguelikes like th...
Edmund McMillen's popular roguelike creation The Binding of Isaac: Rebirth has finally crawled onto mobile devices. It's a grotesque dual-stick shooter that tosses you into an endless, procedurally generated basement as you, the pitiable Isaac,... | Read more »

Price Scanner via MacPrices.net

12-inch 1.2GHz Space Gray Retina MacBook on s...
Amazon has the 2016 12″ 1.2GHz/512GB Space Gray Retina MacBook (Apple model #MLH82LL/A) on sale for $1299.99 including free shipping. Their price is $300 off MSRP. Read more
Twelve South Releases RelaxedLeather Cases fo...
Inspired by the laid-back luxury of burnished leather boots and crafted in rich tones of taupe, herb and marsala, RelaxedLeather cases deliver smart, easy protection for the iPhone 7. Each genuine... Read more
Week’s Best Deal: New 2016 13-inch 2.0GHz Mac...
Amazon has the new 2016 13″ 2.0GHz non-Touch Bar MacBook Pros on sale for a limited time for $225 off MSRP including free shipping: - 13″ 2.0GHz MacBook Pro, Space Gray (MLL42LL/A): $1274.99 $225 off... Read more
Back in stock: Apple refurbished Mac minis fr...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
Apple Ranked ‘Most Intimate Brand’
The top ranked ‘”intimate” brands continued to outperform the S&P and Fortune 500 indices in revenue and profit over the past 10 years, according to MBLM’s Brand Intimacy 2017 Report, the largest... Read more
B-Eng introduces SSD Health Check for Mac OS
Fehraltorf, Switzerland based independant Swiss company- B-Eng has announced the release and immediate availability of SSD Health Check 1.0, the company’s new hard drive utility for Mac OS X. As the... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: -... Read more
4-core 3.7GHz Mac Pro on sale for $2290, save...
Guitar Center has the 3.7GHz 4-core Mac Pro (MD253LL/A) on sale for $2289.97 including free shipping or free local store pickup (if available). Their price is a $710 savings over standard MSRP for... Read more
128GB Apple iPad Air 2, refurbished, availabl...
Apple has Certified Refurbished 128GB iPad Air 2s WiFis available for $419 including free shipping. That’s an $80 savings over standard MSRP for this model. A standard Apple one-year warranty is... Read more
13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 13″ 2.7GHz/128GB Retina Apple MacBook Pro on sale for $100 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $... Read more

Jobs Board

*Apple* macOS Systems Integration Administra...
…most exceptional support available in the industry. SCI is seeking an Junior Apple macOS systems integration administrator that will be responsible for providing Read more
*Apple* Retail - Multiple Positions- Deer Pa...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Technician - nfrastructure (United S...
Let’s Work Together Apple Technician This position is based in Portland, ME Life at nfrastructure At nfrastructure, we understand that our success results from our Read more
*Apple* Mobile Master - Best Buy (United Sta...
**467692BR** **Job Title:** Apple Mobile Master **Location Number:** 000602-Columbia MO-Store **Job Description:** **What does a Best Buy Apple Mobile Master Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.