TweetFollow Us on Twitter

Packagemaker: Delivering Applications

Volume Number: 25
Issue Number: 05
Column Tag: Installers

Packagemaker: Delivering Applications

Learn how to build an application installer for OS X 10.5

By José R.C. Cruz

Introduction

In this article, I will show how to deliver applications for Leopard using an installer package. First, I list situations where an installer package is the better delivery solution. Next, I show how to add an application payload to a package. Then I show how to get the package check for certain target settings. I also show how to get the package choose the right payload for the specific target.

A Survey of Delivery Methods

You can deliver your applications to OS X users in a number of ways. One way is to package the application in a tarball or ZIP archive (Figure 1). When a user double-clicks the archive, the Finder opens the archive with the Archive Utility tool. It then extracts the application and saves it on the same directory as the archive. The user then moves the application to the desired location.


Figure 1. Delivery by tarball

Another way is to package the application in a disk image file (Figure 2). When a user double-clicks the file, the Finder mounts it as a virtual disk volume. The user then copies the application from the image to the correct location. You can also place a link to the preferred directory on that image file as a matter of convenience. You can also have the image file display a ReadMe or License file while being mounted.


Figure 2. Delivery by disk image

Both methods are simple and easy to prepare. They incur zero costs, which makes them popular for open-source and freeware projects. But these methods rely on users knowing how to install the payloads. They also work best if the payload is a single application. A more user-friendly method is to use an installer package.

Delivery by package

Using an installer package as a delivery method has a number of benefits. First, a package can check if the target can run your application. For instance, if the target has the wrong system version, the package tells users of the problem, and then stops the install process. But if the target lacks enough memory, a package can warn those users, yet allow the install process to continue.

A package can install any support files that the application needs. It can route those files to the right locations on the target. It can use SystemStarter to launch those files if necessary. Or it can prompt users to re-login or restart their machines in order to use the application.

A package can handle several variants of the same payload. Assume, for example, you have two variants of the application Foobar. One variant is optimized for PowerPC, the other for x86. The package can first check which CPU the target uses. It then can select and install the right variant for that target.

A package also "forces" users to read important files such as the ReadMe and License files. Users often ignore these files if found in a tarball or disk image. A package also keeps a record of the installation in the /Library/Receipts directory. It then can use this data to handle any upgrades to the application. And a package can run scripts to prepare the target before and after an install session.

But an installer package also has its own downsides. It takes more work to prepare a package than an archive or disk image file. The package is also a bundle format, which needs the use of an archive or disk image file (this is no longer true with Leopard packages). And there are variants of the package format, each variant tuned to a specific version of OS X.

Nevertheless, an installer package is a viable delivery method. Apple itself uses packages to deliver products such as iTunes, iPhoto, and Xcode to its users. These products are prime examples of how an installer package should work.

The Application Payload

Applications come in two forms. Some are executable files. They keep their code and resources in one large file. Some are executable bundles. They keep their code and resources as separate items in one special directory.

PackageMaker 3.0 can handle either format. It also has two new panels wherein you can configure your payload. The Contents panel lets your sets the payload's permission flags, UID, and GID. The Components panel lets you set the relocation and downgrade options of your payload.

The Contents panel

The Contents panel (Figure 3) lists the items that comprise the application payload. It shows the current permissions, UID, and GID of each item. By default, PackageMaker shows the UID and GID that Xcode assigned to the payload and its items. It also shows the octal value 732 as the payload's permissions.


Figure 3. The Contents panel

On the lower left of the panel are the permission controls (red). Use these controls to change the permissions of the selected item from the list. For example, to set the file Info.plist to read-only, first select the file from the list. Then set the checkboxes Read, and clear the checkboxes Write and Execute, for each user type.

Note that changing the permissions of a directory does not change the permissions of its items. Note also that some directories such as .app and Contents must have the Execute flag set. If this flag is not set, the application bundle will not run.

On the lower right of the panel are the UID /GID controls (green). Use these controls to change the UID or GID of the selected item. For instance, to change the UID for Info.plist to root, select the file from the list. Then choose root from the pop-up menu Owner. Again, changing the UID or GID of a directory does not affect its items.

In most cases, you should let the tool assign the correct permissions, UID, and GID to the payload's items. To do so, click the button Apply Recommendations. The tool then updates each item in the payload to the correct set of permissions. It also sets the UID and GID to root and admin respectively.

You can also use the Contents panel to exclude certain items in the payload from the package. For example, to exclude the French.lproj bundle, clear the checkbox next to that bundle's name (Figure 4). When the tool builds the installer package, it does not add French.lproj and its files to that package.


Figure 4. Selecting an item to exclude

Another way to exclude items is with the File Filter dialog (Figure 5). This dialog lists the regex patterns the tool uses to check each items. If the tool finds a matching item, it excludes that item from the package. Those same items will still appear on the list, with their checkboxes set.

To add a pattern to the list, click the '+' button. Then type the string directly on the list. To remove a pattern, select the string from the list, and click the '-' button. To change a pattern, double-click the pattern string on the list. Make sure to click the Save button to keep your changes.


Figure 5. The File Filter dialog

The Components panel

The Components panel (Figure 6) defines how the package handles relocation and downgrades. By default, the package installs its payload at the path set in the Destination field. To let users to change the path, select the checkbox Allow Relocation. Users can then use the Select A Destination panel to select a new destination for the payload.


Figure 6. The Components panel

Also, by default, the package only lets users to do upgrades. If the target has a copy of the payload, the package will replace that copy only with a newer version. To let users install an older version of the payload, set the checkbox Allow Downgrade.

The topics of relocation and downgrades are beyond the scope of this article. I will, however, cover these two topics in a future article. For now, just leave this panel at its default settings.

Preparing The Package

Our demo package Foobar will have two variants of the payload CompositeLab. One variant is for PowerPC targets, the other for Intel targets. The package will check if the target system is version 10.4.4 or newer. It will filter out all target volumes with less than 1 Gbytes of space. It will also warn users if the target has less than 700 Mbytes of physical memory. To keep things simple, we will leave the package's interface elements at their default values.

Start a new project file with PackageMaker. Choose Install Properties from the Project menu. Set the properties dialog as shown in Figure 7. This sets the package's base ID. We're using com.mactech, but feel free to use your own ID.

The dialog also sets the package format based on the minimum target system. If you choose 10.4, the tool will use the distribution package format. This is a bundle format. It stores its localized text, metadata, and scripts in the XML file distribution.dist. It also stores each payload as separate component packages. But like all bundle formats, you must use a tarball or image file to send the package to your users.

Now if you choose 10.5, the tool will use the new Leopard package format. Unlike previous formats, which are bundles, the Leopard format is a flat file. It is simpler to distribute, as it removes the need for a tarball or disk image file. It does not, however, let you change the package after building it. It is also supported only on MacOS X 10.5.


Figure 7. Setting the Install Properties

Next, click the icon Foobar at the top of the payload list. Select the Configuration tab to display the editor subpanel. Update the subpanel as shown in Figure 8. The settings tell the package to display only the Custom Install panel. It also tells the package to let users choose the desired target volume.


Figure 8. Configuring the package

Adding the payloads

Choose Add Contents from the Project menu. Select the application Composite (PPC).app with the sheet dialog, and click the Choose button. PackageMaker then adds an entry for that payload in the payload list. It also updates its Configuration panel as shown in Figure 9. Use the same steps to select the application Composite (x86).app.


Figure 9. Configuring the payload

Notice the tool sets the destination path for both payloads to /Applications. The tool also sets the checkbox Allow custom location. It sets the pop-up menu Restart Action to None, and selects the checkbox Require admin authentication.

Configuring the contents

Select the payload CompositeLab (PPC) from the payload list. Click the Contents tab on the editor panel. You should see the payload bundle displayed on the Contents list. To view the bundle's items, click the triangle next to its name (Figure 10).


Figure 10. Configuring the payload contents

As stated earlier, PackageMaker sets the UID and GID of each item to your username and group. Now click the button Apply Recommendations. The tool will change the UID and GID to root and admin. Apple uses these same settings for its Cocoa products.

Locate and select the file BBalls.icns from the Contents list. Using the permission controls, set that file as read-only for all users, you included. Repeat the same steps for the file Info.plist. Leave the permissions for the rest of the bundle items unchanged.

Now, select the payload CompositeLab (x86) from the payload list. Use the same steps to configure the bundle contents of that payload.

Setting target requirements

Now, click the Foobar icon at the top of the payload list. Select the Requirements tab on the editor panel. Then click the '+' button at the bottom left of the list to display the Requirements Editor.

Update the editor as shown in Figure 11. Click the OK button to save your settings. These settings tell the package to check if the target OS is at least version 10.4.4. If the check proves true, the package continues the install session. If false, it displays the failure message and ends the session.


Figure 11. Checking for OS version

Notice that there are actually two checks for OS versions. One checks the system version, the other the target version. System is where you are hosting the package. It is where you opened the package using Installer. Target is where you want to install the payload. It also has the volumes that may contain the payload.

In most cases, system and target refer to the same thing. This is the assumption I make in this article. But there are cases when system and target are not the same. Figure 12 is one example of such case. Here, the package is on a server running OS X 10.4. It installs its payload onto a network client running OS X 10.5. So, in this example, the 10.4 server is the system and the 10.5 client is the target.


Figure 12. Delivery via a network

Time to add the memory check. Click the '+' button to display the Requirements Editor. Update the editor as shown in Figure 13. Click the OK button to save your settings. These settings tell the package to check if the target has at least 700 Mbytes of physical memory. If the check proved false, the package displays the failure message. Notice that the memory amount is expressed in bytes.


Figure 13. Checking for physical memory

Unlike the OS version check, the memory check only checks the system. But like the OS version check, the memory check also ends the session if it is false. To change this behavior, select its entry on the Requirements list. Click the Required column, and change the entry from Required to Optional (Figure 14). Now, when the check proved false, it will still let users continue with the install session.


Figure 14. Making the check optional

Bring up the Requirements Editor once again. This time, update the editor as shown in Figure 15. Click the OK button to save the settings. These settings tell the package to check each mounted volume on the target. If it finds a volume with less than 700 Mbytes of free space, the package will not install its payload on that volume. It will also display the specified failure message for that volume.


Figure 15. Checking for volume space

The package runs each check at different points in the install session. It runs the check for the target's OS version and memory right after it shows its Welcome panel. But it runs the volume check after it shows the Select A Destination panel. Knowing where each check is done will help debug any problems found in the package.

Configuring the choices

The next step is to configure each payload choice. Click the choice CompositeLab (PPC) from the payload list. Select the Configuration tab on the editor panel. Update the panel as shown in Figure 16. These settings enable and select the choice by default. They also set the description and tooltip message of this choice.


Figure 16. Configuring the PowerPC payload

Now select the Requirements tab from the editor panel. Click the '+' button to display the Requirements Editor. Then update the editor as shown in Figure 17. These settings tell the package to check the system CPU using a sysctl() call. If the CPU is a PowerPC, the package leaves the choice unchanged. Otherwise, the package deselects and disables the choice.


Figure 17. Checking for a PowerPC CPU

Next, click the payload choice CompositeLab (x86). Update its Configuration subpanel as shown in Figure 18. Again, the settings select and enable this choice by default. They also set the description and tooltip message of this choice.


Figure 18. Configuring the x86 payload

Go to the Requirements subpanel and display its editor. Update the editor as shown in Figure 19. Again, the settings tell the package to check the system CPU using a sysctl() call. If the CPU is an x86 or Intel processor, the package leaves the choice unchanged. Otherwise, it deselects and disables the choice.


Figure 19. Checking for an x86 CPU

Testing The Package

I will now show how to test your package. First, choose Build from the Project menu. PackageMaker then prompts you for a package name. Type Foobar on the Save File dialog and click the Save button.

Then go to the Finder and locate the Foobar package. Double-click the package to start an install session. If all goes well, the package should display its Welcome panel.

Testing requirements

After the package displays its Welcome panel, it first runs the OS version check. If your target is running 10.5, it should pass the OS version check. But if it is running 10.4.3 or older, you should get the error dialog in Figure 20. Clicking the Close button should end the install session. If these do not happen, recheck your requirements settings and rebuild the package.

The OS version check, however, does not apply if the package uses the new flat file format. Again, this is because only 10.5 will support the new format.


Figure 20. The OS version check fails

Once the target passes the OS version check, the package then runs the memory check. If the target has less than 700 Mbytes of memory, the package should display the warning dialog in Figure 21. But clicking the OK button should not end the install session. Instead, it should dismiss the dialog and return you to the Welcome panel.


Figure 21. The memory check has failed

Now, click the Continue button on the Welcome panel. The package then displays the Select A Destination panel (Figure 22), showing a list of target volumes. It then runs the volume check on each mounted volume. If a volume fails the check, its icon gets a stop badge. Selecting that volume will display the error message. But if a volume passes the check, selecting that volume displays a green arrow on its icon (Figure 23). And, placing the cursor over any volume icon, pass or fail, displays that volume's mount info.


Figure 22. Selecting a volume that failed the check


Figure 23. Selecting a volume that passed the check

Testing choices

After you have selected a target volume, click the Continue button to go to the Custom Install panel. If the package does not display this panel, you may have disabled this setting. Make sure you have configured your package as shown in Figure 8.

On a PowerPC target, the package should enable and selected the payload CompositeLab (PPC). It should also disable the payload CompositeLab (x86) as shown in Figure 24. The reverse should happen if the target is an Intel one. Also, if you select either choice, you should see its description displayed on the field below the choice list. And if you place the arrow cursor over each choice, you should see the tooltip message for that choice.


Figure 24. Choosing the PowerPC payload

If none of these happen, check again your settings for that choice. You may also want to check the target to see if it returns a different sysctl() value. Start a Terminal session and type the following at the prompt.

   sysctl hw.cputype

If the target returns a value different from 18 or 7, use that value to enable the right payload.

Testing payloads

Once you confirmed the right payload selected, click the Continue button to display the Standard Install panel. Then click the Install button to install the payload.

First, the package asks you to enter an admin password. Enter the password and click the OK button. If the password is correct, the package then installs its payload onto the target volume. It then displays the Conclusion panel shown in Figure 25.


Figure 25. The concluding panel

If you enter the wrong password thrice, the package should return you to the Standard Install panel. Also, if the package fails to install its package, it should display a red circle with a white cross on its Conclusions panel.

Now, check the target volume that you have selected. You should find the payload inside an Application directory. You should also find a /Library/Receipts directory at the volume's top level. That directory's contents should be the files shown in Figure 26. These files serve as a record of your install session.


Figure 26. The results of the installation

If you find these items installed on the target, your install session is indeed successful.

Concluding Remarks

This article showed some of the benefits of using an installer package to deliver applications. The package can install the right payload for a given target. It can check the target for resources needed by the payload. It can set the correct permissions, UID, and GID to the payload. It also makes a record of the install session on the target.

Next time, I will cover the new scripting features of PackageMaker 3.0. I will show how to add an installer script to the package. I will also show how to write and edit a script using the Requirements Editor.

Until next time, relax and have a cup of tea.

Bibliography and References

Apple Computers. PackageMaker Users Guide. 2007 Jul 23. Copyright 2007. Apple Computers, Inc. Online:

http://developer.apple.com/DOCUMENTATION/DeveloperTools/Conceptual/PackageMakerUserGuide/Introduction/chapter_1_section_1.html

Apple Computers. Software Delivery Guide. 2006 Jul 24. Copyright 2006. Apple Computers, Inc. Online:

http://developer.apple.com/documentation/DeveloperTools/Conceptual/SoftwareDistribution/Introduction/chapter_1_section_1.html

Apple Computers. Installing Your Application on MacOS X: Guidelines for Developers. 2005 Jul 07. Copyright 2008. Apple Computers, Inc. Online:

http://developer.apple.com/tools/installerpolicy.html


JC is a freelance engineering writer from North Vancouver, British Columbia. He spends his time writing technical articles; tinkering with Cocoa, REALbasic, and Python; and visiting his foster nephew. He can be reached at anarakisware@gmail.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Viber 6.8.6 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Carbon Copy Cloner 4.1.17 - Easy-to-use...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
EtreCheck 3.4.2 - For troubleshooting yo...
EtreCheck is an app that displays the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support Communities to... Read more
Hopper Disassembler 4.2.10- - Binary dis...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
VueScan 9.5.81 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
iFFmpeg 6.4.2 - Convert multimedia files...
iFFmpeg is a comprehensive media tool to convert movie, audio and media files between formats. The FFmpeg command line instructions can be very hard to master/understand, so iFFmpeg does all the hard... Read more
Fantastical 2.4.1 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Fantastical 2.4.1 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Live Home 3D Pro 3.2.2 - $69.99
Live Home 3D Pro, a successor of Live Interior 3D, is the powerful yet intuitive home design software that lets you build the house of your dreams right on your Mac. It has every feature of Live Home... Read more
Live Home 3D Pro 3.2.2 - $69.99
Live Home 3D Pro, a successor of Live Interior 3D, is the powerful yet intuitive home design software that lets you build the house of your dreams right on your Mac. It has every feature of Live Home... Read more

Latest Forum Discussions

See All

Glyph Quest Chronicles guide - how to ma...
Glyph Quest returns with a new free-to-play game, Glyph Quest Chronicles. Chronicles offers up more of the light-hearted, good humored fantasy fun that previous games featured, but with a few more refined tricks up its sleeve. It's a clever mix of... | Read more »
Catch yourself a Lugia and Articuno in P...
Pokémon Go Fest may have been a bit of a disaster, with Niantic offering fans full refunds and $100 worth of in-game curency to apologize for the failed event, but that hasn't ruined trainers' chances of catching new legendary Pokémon. Lugia nad... | Read more »
The best deals on the App Store this wee...
There are quite a few truly superb games on sale on the App Store this week. If you haven't played some of these, many of which are true classics, now's the time to jump on the bandwagon. Here are the deals you need to know about. [Read more] | Read more »
Realpolitiks Mobile (Games)
Realpolitiks Mobile 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: PLEASE NOTE: The game might not work properly on discontinued 1GB of RAM devices (iPhone 5s, iPhone 6, iPhone 6 Plus, iPad... | Read more »
Layton’s Mystery Journey (Games)
Layton’s Mystery Journey 1.0.0 Device: iOS Universal Category: Games Price: $15.99, Version: 1.0.0 (iTunes) Description: THE MUCH-LOVED LAYTON SERIES IS BACK WITH A 10TH ANNIVERSARY INSTALLMENT! Developed by LEVEL-5, LAYTON’S... | Read more »
Full Throttle Remastered (Games)
Full Throttle Remastered 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Originally released by LucasArts in 1995, Full Throttle is a classic graphic adventure game from industry legend Tim... | Read more »
Stunning shooter Morphite gets a new tra...
Morphite is officially landing on iOS in September. The game looks like the space shooter we've been needing on mobile, and we're going to see if it fits the bill quite shortly. The game's a collaborative effort between Blowfish Studios, We're Five... | Read more »
Layton's Mystery Journey arrives to...
As you might recall, Layton's Mystery Journey is headed to iOS and Android -- tomorrow! To celebrate the impending launch, Level-5's released a new trailer, complete with an adorable hamster. [Read more] | Read more »
Sidewords (Games)
Sidewords 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Grab a cup of coffee and relax with Sidewords. Sidewords is part logic puzzle, part word game, all original. No timers. No... | Read more »
Noodlecake Games' 'Leap On!...
Noodlecake Games is always good for some light-hearted arcade fun, and its latest project, Leap On! could carry on that tradition. It's a bit like high stakes tetherball in a way. Your job is to guide a cute little blob around a series of floating... | Read more »

Price Scanner via MacPrices.net

Apple Move Away from White Label Event Apps C...
DoubleDutch, Inc., a global provider of Live Engagement Marketing (LEM) solutions, has made a statement in the light of a game-changing announcement from Apple at this year’s WWDC conference.... Read more
70 Year Old Artist Creates Art Tools for the...
New Hampshire-based developer Pirate’s Moon has announced MyArtTools 1.1.3, the update to their precision drawing app, designed by artist Richard Hoeper exclusively for use with the 12.9-inch iPad... Read more
Sale! New 2017 13-inch 2.3GHz MacBook Pros fo...
Amazon has new 2017 13″ 2.3GHz/128GB MacBook Pros on sale today for $150 off MSRP including free shipping. Their prices are the lowest available for these models from any reseller: – 13″ 2.3GHz/128GB... Read more
13″ 2.3GHz/128GB Space Gray MacBook Pro on sa...
MacMall has the 13″ 2.3GHz/128GB Space Gray MacBook Pro (MPXQ2LL/A) on sale for $1219 including free shipping. Their price is $80 off MSRP. Read more
Clearance 2016 12-inch Retina MacBooks, Apple...
Apple recently dropped prices on Certified Refurbished 2016 12″ Retina MacBooks, with models now available starting at $1019. Apple will include a standard one-year warranty with each MacBook, and... Read more
Save or Share
FotoJet Designer, is a simple but powerful new graphic design apps available on both Mac and Windows. With FotoJet Designer’s 900+ templates, thousands of resources, and powerful editing tools you... Read more
Logo Maker Shop iOS App Lets Businesses Get C...
A newly released app is designed to help business owners to get creative with their branding by designing their own logos. With more than 1,000 editable templates, Logo Maker Shop 1.0 provides the... Read more
Sale! New 15-inch MacBook Pros for up to $150...
Amazon has the new 2017 15″ MacBook Pros on sale for up to $150 off MSRP including free shipping: – 15″ 2.8GHz MacBook Pro Space Gray: $2249 $150 off MSRP – 15″ 2.89Hz MacBook Pro Space Gray: $2779 $... Read more
DEVONthink To Go 2.1.7 For iOS Brings Usabili...
DEVONtechnologies has updated DEVONthink To Go, the iOS companion to DEVONthink for Mac, with enhancements and bug fixes. Version 2.1.7 adds an option to clear the Global Inbox and makes the grid... Read more
15-inch 2.2GHz Retina MacBook Pro, Apple refu...
Apple has Certified Refurbished 2015 15″ 2.2GHz Retina MacBook Pros available for $1699. That’s $300 off MSRP, and it’s the lowest price available for a 15″ MacBook Pro. An Apple one-year warranty is... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Poole -...
Job Summary The people here at Apple don't just create products - they create the kind of wonder that's revolutionised entire industries. It's the diversity of those Read more
SW Engineer *Apple* TV - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Product Manager - *Apple* Pay on the *Appl...
Job Summary Apple is looking for a talented product manager to drive the expansion of Apple Pay on the Apple Online Store. This position includes a unique Read more
*Apple* Retail - Multiple Positions - Apple...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.