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

Bookends 13.2.6 - 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
BusyContacts 1.4.0 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
Chromium 77.0.3865.75 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 77.0.3865.75: A list of changes is available... Read more
DiskCatalogMaker 7.5.5 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Alfred 4.0.4 - Quick launcher for apps a...
Alfred is an award-winning productivity application for OS X. Alfred saves you time when you search for files online or on your Mac. Be more productive with hotkeys, keywords, and file actions at... Read more
A Better Finder Rename 10.45 - File, pho...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
iFinance 4.5.11 - Comprehensively manage...
iFinance allows you to keep track of your income and spending -- from your lunchbreak coffee to your new car -- in the most convenient and fastest way. Clearly arranged transaction lists of all your... Read more
OmniGraffle Pro 7.11.3 - Create diagrams...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
BBEdit 12.6.7 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
OmniGraffle 7.11.3 - Create diagrams, fl...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more

Latest Forum Discussions

See All

Five Nights at Freddy's AR: Special...
Five Nights at Freddy's AR: Special Delivery is a terrifying new nightmare from developer Illumix. Last week, FNAF fans were sent into a frenzy by a short teaser for what we now know to be Special Delivery. Those in the comments were quick to... | Read more »
Rush Rally 3's new live events are...
Last week, Rush Rally 3 got updated with live events, and it’s one of the best things to happen to racing games on mobile. Prior to this update, the game already had multiplayer, but live events are more convenient in the sense that it’s somewhat... | Read more »
Why your free-to-play racer sucks
It’s been this way for a while now, but playing Hot Wheels Infinite Loop really highlights a big issue with free-to-play mobile racing games: They suck. It doesn’t matter if you’re trying going for realism, cart racing, or arcade nonsense, they’re... | Read more »
Steam Link Spotlight - The Banner Saga 3
Steam Link Spotlight is a new feature where we take a look at PC games that play exceptionally well using the Steam Link app. Our last entry talked about Terry Cavanaugh’s incredible Dicey Dungeons. Read about how it’s a great mobile experience... | Read more »
PSA: GRIS has some issues
You may or may not have seen that Devolver Digital just released GRIS on the App Store, but we wanted to do a quick public service announcement to say that you might not want to hop on buying it just yet. The puzzle platformer has come to small... | Read more »
Explore the world around you in new matc...
Got a hankering for a fresh-feeling Match-3 puzzle game that offers a unique twist? You might find exactly what you’re looking for with What a Wonderful World, a new spin on the classic mobile genre which merges entertaining puzzles with global... | Read more »
Combo Quest (Games)
Combo Quest 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Combo Quest is an epic, time tap role-playing adventure. In this unique masterpiece, you are a knight on a heroic quest to retrieve... | Read more »
Hero Emblems (Games)
Hero Emblems 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ** 25% OFF for a limited time to celebrate the release ** ** Note for iPhone 6 user: If it doesn't run fullscreen on your device... | Read more »
Puzzle Blitz (Games)
Puzzle Blitz 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Puzzle Blitz is a frantic puzzle solving race against the clock! Solve as many puzzles as you can, before time runs out! You have... | Read more »
Sky Patrol (Games)
Sky Patrol 1.0.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.1 (iTunes) Description: 'Strategic Twist On The Classic Shooter Genre' - Indie Game Mag... | Read more »

Price Scanner via MacPrices.net

Sunday Sale! 2019 27″ 5K 6-Core iMacs for $20...
B&H Photo has the new 2019 27″ 5K 6-Core iMacs on stock today and on sale for up to $250 off Apple’s MSRP. Overnight shipping is free to many locations in the US. These are the same iMacs sold by... Read more
Weekend Sale! 2019 13″ MacBook Airs for $200...
Amazon has new 2019 13″ MacBook Airs on sale for $200 off Apple’s MSRP, with prices starting at $899, each including free shipping. Be sure to select Amazon as the seller during checkout, rather than... Read more
2019 15″ MacBook Pros now on sale for $350-$4...
B&H Photo has Apple’s 2019 15″ 6-Core and 8-Core MacBook Pros on sale today for $350-$400 off MSRP, starting at $2049, with free overnight shipping available to many addresses in the US: – 2019... Read more
Buy one Apple Watch Series 5 at Verizon, get...
Buy one Apple Watch Series 5 at Verizon, and get a second Watch for 50% off. Plus save $10 on your first month of service. The fine print: “Buy Apple Watch, get another up to 50% off on us. Plus $10... Read more
Sprint offers 64GB iPhone 11 for free to new...
Sprint will include the 64GB iPhone 11 for free for new customers with an eligible trade-in in of the iPhone 7 or newer through September 19, 2019. The fine print: “iPhone 11 64GB $0/mo. iPhone 11... Read more
Verizon offers new iPhone 11 models for up to...
Verizon is offering Apple’s new iPhone 11 models for $500 off MSRP to new customers with an eligible trade-in (see list below). Discount is applied via monthly bill credits over 24 months. Verizon is... Read more
AT&T offers free $300 reward card + free...
AT&T Wireless will include a second free 64GB iPhone 11 with the purchase of one eligible iPhone at full price. They will also include a free $300 rewards card. The fine print: “Buy an elig.... Read more
US Cellular offers 64GB iPhone 11 for free to...
US Cellular is offering the base 64GB iPhone 11 for free for new customers. Qualified trade-in of iPhone 7 or higher required (or a number of Android phones). Discounts are applied via monthly bill... Read more
New 7th generation 10.2″ 128GB iPads availabl...
Amazon is accepting preorders for Apple’s new 7th generation 10.2″ 128GB iPads for $399.99 each, or $30 off Apple’s MSRP for this model. Shipping is free: – 10.2″ 128GB WiFi iPad Space Gray: $399.99... Read more
Sprint has the new 7th Generation iPad on sal...
Sprint has the new 2019 7th Generation 32GB WiFi + Cellular iPad available starting at only $99.99 from 9/12/19 to 10/3/19. Their price is a $360 savings over Apple’s standard MSRP. See the deal live... Read more

Jobs Board

Geek Squad *Apple* Master Consultation Agen...
**732131BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Job Category:** Services/Installation/Repair **Location Number:** 000399-Wausau-Store **Job Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**723452BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Location Number:** 001194-Greeley-Store **Job Description:** At Best Buy, our Read more
Best Buy *Apple* Computing Master - Best Bu...
**732027BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Location Number:** 002507-Alexandria-Store **Job Description:** The Read more
Best Buy *Apple* Computing Master - Best Bu...
**727669BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000890-Buckhead-Store **Job Description:** **What does a Read more
Geek Squad *Apple* Master Consultation Agen...
**731944BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Job Category:** Services/Installation/Repair **Location Number:** 001130-Nashville Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.