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.

 
AAPL
$100.89
Apple Inc.
-0.65
MSFT
$45.01
Microsoft Corpora
-0.17
GOOG
$577.86
Google Inc.
-2.34

MacTech Search:
Community Search:

Software Updates via MacUpdate

BBEdit 10.5.12 - Powerful text and HTML...
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
Microsoft Office 2011 14.4.4 - Popular p...
Microsoft Office 2011 helps you create professional documents and presentations. And since Office for Mac 2011 is compatible with Office for Windows, you can work on documents with virtually anyone... Read more
TextWrangler 4.5.10 - Free general purpo...
TextWrangler is the powerful general purpose text editor, and Unix and server administrator's tool. Oh, and also, like the best things in life, it's free. TextWrangler is the "little brother" to... Read more
BitTorrent Sync 1.4.72 - Sync files secu...
BitTorrent Sync allows you to sync unlimited files between your own devices, or share a folder with friends and family to automatically sync anything. File transfers are encrypted. Your information... Read more
Cyberduck 4.5.2 - FTP and SFTP browser....
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Tinderbox 6.0.3 - Store and organize you...
Tinderbox is a personal content management assistant. It stores your notes, ideas, and plans. It can help you organize and understand them. And Tinderbox helps you share ideas through Web journals... Read more
Adobe Photoshop CC 2014 15.1.0 - Profess...
Photoshop CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Photoshop customer). Photoshop CS6 is still available for purchase (... Read more
Adobe InDesign CC 2014 10.0.0.70 - Profe...
InDesign CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous InDesign customer). InDesign CS6 is still available for purchase (... Read more
Adobe InCopy CC 2014 10.0.0.70 - Create...
InCopy CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous InCopy customer). InCopy CS6 is still available for purchase (without a... Read more
Adobe Illustrator CC 2014 18.0 - Profess...
Illustrator CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Illustrator customer). Illustrator CS6 is still available for... Read more

Latest Forum Discussions

See All

8bit Doves (Games)
8bit Doves 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: “I dove it” – Pocket Gamer “They told me I could be whatever I want, so I became a flying hobo” – Cactus Wolf “Let’s you crash into... | Read more »
Madden NFL Mobile Review
Madden NFL Mobile Review By Blake Grundman on August 26th, 2014 Our Rating: :: FINALLY GETS IT RIGHTUniversal App - Designed for iPhone and iPad It looks like EA Sports has finally discovered how to tread the line between free-to-... | Read more »
Superhero Workout Review
Superhero Workout Review By Jennifer Allen on August 26th, 2014 Our Rating: :: SUPERCHARGEDUniversal App - Designed for iPhone and iPad Want a workout with a kind of story tied into it? Superhero Workout is what you’re after.   | Read more »
Star Wars: Commander Review
Star Wars: Commander Review By Jennifer Allen on August 26th, 2014 Our Rating: :: CLASH OF THE FORCEUniversal App - Designed for iPhone and iPad It’s a lot like Clash of Clans, but the use of the Star Wars license means you don’t... | Read more »
Ridge Racer Slipstream Update Adds New C...
Ridge Racer Slipstream Update Adds New Cars, Challenges, and Tracks Posted by Ellis Spice on August 26th, 2014 [ permalink ] | Read more »
Infinity Blade III: Kingdom Come, the Fi...
Infinity Blade III: Kingdom Come, the Final Update, Set to Arrive September Posted by Ellis Spice on August 26th, 2014 [ permalink ] | Read more »
Furious Climber Review
Furious Climber Review By Jordan Minor on August 26th, 2014 Our Rating: :: REACH FOR THE STARSUniversal App - Designed for iPhone and iPad Furious Climber’s rough packaging can’t ruin its awesomely awkward gameplay   | Read more »
Don’t Forget the Milk – Let Heap, the Gr...
Don’t Forget the Milk – Let Heap, the Grocery List App, Help You Stay Organized While Shopping Posted by Jessica Fisher on August 26th, 2014 [ permalink ] | Read more »
MZR Review
MZR Review By Rob Thomas on August 26th, 2014 Our Rating: :: MAZED AND CONFUSEDUniversal App - Designed for iPhone and iPad How quickly can you escape from MZR’s neon mazes of doom? Why not find out for yourself?   | Read more »
Take Note – Livescribe Partners with Mol...
Take Note – Livescribe Partners with Moleskine to Make Livescribe Notebooks, Available Now Posted by Jessica Fisher on August 26th, 2014 [ permalink ] Livescribe has announced a partne | Read more »

Price Scanner via MacPrices.net

Life Inventory iOS Apps – Learn to Know Thyse...
James Hollender’s Life Inventory apps s are now on sale with 20% off thru Labor Day, 09/01/2014. This is a great opportunity to get started on that Moral Inventory you’ve been putting off doing for... Read more
Pocket Watch, LLC. Reveals Cloud Server For P...
Beaumont, Texas based Pocket Watch, LLC. has announced the availability of its new ActivePrint Cloud Server Powered by Raspberry Pi. With this small standalone box almost any USB printer or available... Read more
902it Simplifies Area Code Changes For Nova S...
The east coast Canadian provinces of Nova Scotia and Prince Edward Island are phasing in 10 digit telephone dialing, to be fully in place by November, in order to accommodate a second area code to... Read more
Boomerang iPad Stand Mounts Your iPad Anywher...
Boomerang, a Mountable Stand with Multiple Viewing Angles, is now available for iPad Air. Boomerang combines several functions that aim to expand your iPad’s potential in one, elegant product. The... Read more
Retina MacBook Pros available starting at $10...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available starting at $929. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros (4GB RAM/... Read more
Apple 27-inch Thunderbolt Display (refurbishe...
The Apple Store has Apple Certified Refurbished 27″ Thunderbolt Displays available for $799 including free shipping. That’s $200 off the cost of new models. Read more
Apple offers free $25 iTunes gift card with p...
The Apple Store is offering a free $25 iTunes Gift Card with the purchase of a $99 Apple TV for a limited time. Shipping is free. Read more
Apple’s 2014 Back to School promotion: $100 g...
 Apple’s 2014 Back to School promotion includes a free $100 App Store Gift Card with the purchase of any new Mac (Mac mini excluded), or a $50 Gift Card with the purchase of an iPad or iPhone,... Read more
iPhone Camera vs. Top Tier DSLR In Picture Qu...
If you’ve wondered just how good the iPhone 5s’s 8 megapixel rear-facing camera is in terms of image quality, The Verge has posted an excellent feature that should remove any ambiguity on the matter... Read more
Apple Announces Limited iPhone 5 Defective Ba...
Apple says it has determined that a very small percentage of iPhone 5 devices may suddenly experience shorter battery life or need to be charged more frequently. The affected iPhone 5 units were sold... Read more

Jobs Board

Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** Being a Business Manager at an Apple Store means you're the catalyst for businesses to discover and leverage the power, ease, and flexibility of Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.