TweetFollow Us on Twitter

Packaging for Leopard

Volume Number: 24 (2008)
Issue Number: 06
Column Tag: Programming

Packaging for Leopard

Introducing the new PackageMaker 3.0

by José R.C. Cruz

Introduction

In today's article, we will look at the new PackageMaker tool. We will learn what new features the tool brings to the developer table, as well as issues that plague it. We will also see what has changed in the tool since its 2.0 version. Finally, we will use the tool to build a basic installer package, and localize it for two regions.

You can get a copy of the project files used in this article. Just go to the following URL to download the files at the MacTech website: ftp.mactech.com/src/mactech/volume24_2008/24.06.sit

Enter PackageMaker 3.0

This latest release of the tool fixes many of the issues found in version 2.0. It boasts a new user interface, and has improved support for scripts and localized files. It is also optimized for Leopard, also known as MacOS X 10.5.

As before, PackageMaker 3.0 is part of the Xcode suite of tools. It is not available as a separate download.

The Project Window

The project window (Figure 1) is where you add and manage the payloads of your package. It is where you configure each payload or the entire package. It also is where you define how the package behaves during installation. And now, you can have several project windows open, each one for a different package.

Figure 1. The Project Window

The window's layout is simpler and less confusing to use than its 2.0 version. It consists of two parts: the payload list and the editor panel.

On the left of the window is the payload list. This list shows each payload in the package and its assigned choice label. At the top of the list is the package bundle, under which the payloads and support files are stored.

On the right of the window is the editor panel. This panel has three different layouts, each layout displayed by selecting an entry from the list. Also, each layout has more than one subpanel, each subpanel selected by a tab button.

Selecting the package name displays the subpanels in Figure 2. The Configuration subpanel sets the target volume(s) for the package. It selects one of three installation modes: easy, custom, or both. It also sets the general description of the package.

Figure 2. Configuring the package

The Requirements subpanel defines what checks to make on the target platform. It creates the InstallationCheck and VolumeCheck scripts used by the package. The Actions subpanel defines how the package behaves before and after installing its payloads. It creates the preinstall and postinstall scripts used by the package.

Selecting a payload choice displays the subpanels shown in Figure 3. The Configuration subpanel sets the name and description of the choice. It sets the choice's unique ID, tooltip message, and default location on the target volume. It also sets the initial state of the choice.

The Requirements subpanel defines what checks to make on the target. The results of these checks then update the state of the payload choice.

Figure 3. Configuring a payload choice

Finally, selecting a payload displays the subpanels shown in Figure 4. The Configuration subpanel sets the location of the payload on the user volume. It assigns a unique ID and version number to each payload. It also defines what action is required from users before they use the payload.

The Contents subpanel sets the permission flags for each item in the payload. If the payload happens to be a bundle, those flags also affect the files and directories inside that bundle. The Components subpanel defines if the payload can be downgraded or relocated. It also defines what scripts to run for those actions. And the Scripts subpanel selects what scripts to run when the payload is installed.

Figure 4. Configuring the payload

The Requirements Editor

The Requirements Editor is where you define the checks to be done on the target platform. Access to the editor is done by clicking on the '+' button on the Requirements panel. Like the payload window, the editor has changed a lot since version 2.0. It is now much simpler and more intuitive to use.

The editor comes in two forms. The first form (Figure 5) is displayed for the package. The upper half of the editor sets the condition a target must satisfy for the package. The lower half sets the failure message. If the target fails a specific condition, the package displays the message set for that condition.

Figure 5. Requirements for a package

The second form (Figure 6) is displayed for a payload choice. As before, the upper half sets the condition a target must satisfy for the choice. The lower right widgets set the initial state of the choice. The lower left widgets set the new state of the choice if the target fails the condition.

Figure 6. Requirements for a payload choice

The editor supports a large variety of conditions. Some conditions focus on the target system, others on the target volumes. Some can check for specific states or setups by calling sysctl() or IORegistry.

The editor can also use an external script to do more complex checks. The script can either be a basic shell script, or one written in Installer JavaScript. Either way, the script must return a TRUE if the check is successful, FALSE if otherwise. The editor also merges the script into the package bundle.

The Interface Editor

The Interface Editor (Figure 7) is where you set the visual aspects of your installer package. This editor changed the least since version 2.0. It now supports localized graphics and text, and it discarded the Contents panel. The rest of the editor, however, works in the same way as before.

Figure 7. The Interface Editor

The editor window has four basic parts. On the left of the window is a list of panel names. Clicking on a name selects the specified panel. The same also happens if you click on the Continue button.

On the right of the window is the settings drawer. This drawer lets you select the file to be used by the panel. It also allows you to enter text directly on the panel.

At the bottom of the window are three region controls. The '+' button adds a new region to the package, the '-' button removes the current region. And the pop-up menu selects which region the panel uses. By default, the editor uses English as its region.

Notable 3.0 issues

As always, the PackageMaker tool has a number of issues that can limit its overall usefulness. The following are some of the issues found in the 3.0 version of the tool. Be aware that a new version of the tool maybe available by the time you read this article.

  • The tool no longer lets you localize the text of each payload choice. Instead, you have to add the localize text directly to the distribution.dist file.

  • The tool lacks any debug or trace functions for installer scripts. Your only recourse is to use the JavaScript method system.log().

  • The Requirements Editor no longer lets you use an external editor to write an installer script. This can make writing long and complex scripts a tedious task.

  • The tool uses Xcode as its online help viewer. Xcode is a very poor choice due to its large resource needs. A better choice for a viewer would be Safari or Apple Help.

  • The tool lacks any support for Automator workflows. This makes the tool difficult to use as part of an automated build and dispatch process.

Let's Make A Package

Now, we will build a basic installer package using the PackageMaker tool. Our payloads are two sets of AppleScript scripts for BBEdit. We will give users the option of choosing which payload to install. We will also have the package check which target volume has enough space.

Adding the payloads

First, prepare the payloads as shown in Figure 8. Notice that each payload is arranged in terms of their location on the target volume. Notice also that the name for each payload directory reflects the actual payload. For instance, the menu action scripts for BBEdit are in the directory named menuAction.

Figure 8. Arranging the payloads

Now launch the PackageMaker tool to start a new installer project. Enter a unique package ID in the Install Properties dialog (Figure 9). Choose the minimum system version from the pop-up button. The tool uses this information to set the bundle format of the package.

Choose Save As... from the File menu, and save the project under the name Foobar.

Figure 9. The Install Properties dialog.

Next, choose Add Contents from the Project menu. Navigate to the foobar directory (see Figure 8), and select the subdirectory menuAction. You should see an entry for this payload on the payload list. Select the entry and click on the Configuration tab on the editor panel. Update the subpanel as shown in Figure 10.

Figure 10. Configuring the payload choice

Follow the same steps to add the payload scriptMenu to the project. Then edit the Configuration subpanel of that choice with its own unique information. You can get the correct information by examining the Foobar project.

Make sure, however, to leave the Destination field blank for both payloads.

Configuring the package

First, click on the Foobar icon from the payload list. Then click on the Configuration tab of the editor panel. Update the subpanel as shown in Figure 11. You can also enter a short description of the package in the Description field, or you can leave that field blank.

These settings allow a user to choose specific payloads. They also let payloads to be installed in either the user's home directory or on a selected target volume.

Figure 11. Configuring the package

Next, click on the Requirements tab to display that subpanel. Click on the '+' button to display the Requirements Editor. Enter the settings shown in Figure 12, and click on the OK button. The subpanel will display the settings as shown in Figure 13.

These settings tell the package to display only those target volumes with at least 1024 Mbytes of free space. They, however, do not apply if the user chooses his home directory as the target.

Figure 12. Configuring the space requirements.

Figure 13. A list of package requirements

Now, click on the payload entry menuAction from the list. Then click on the Configuration tab to display its subpanel (Figure 14). Click to clear the checkbox Require admin authentication. Choose "None" from the pop-up button Restart Action. Leave the rest at their default values.

These settings disable the need to authenticate the payload before it is installed. It also disables the need to restart the target system after installing the payload.

Repeat the same steps for the payload entry scriptMenu.

Figure 14. Configuring the payload.

Building and testing the package

Choose Build from the Project menu. The tool prompts you to save the package under the name Foobar. Change the name to Foobar Installer, and click on the Save button to save the package under that name.

The tool then switches to its progress window (Figure 15). It displays each stage of the build, as well as any issues it finds. In the example shown, the tool displays two build warnings. The first warning tells us that we have disabled authentication. This is an issue only if our payloads consist of critical code such as drivers or frameworks. Since our payloads are just user-level scripts, we can ignore this warning.

The second warning tells us that installing into the user's home directory works only for versions 10.5 or newer of MacOS X. Older versions of MacOS X will not support this option. Again, just ignore this warning, as it does not affect our needs at this time.

Figure 15. The build progress window

To test the package, click on the window icon Open In Installer. The tool will now tell the Installer utility to open the installer package. After the Installer displays its first panel, click on the Continue button until you see the panel Select A Destination. Then click on the icon Install on a specific hard drive to display a list of target volumes (Figure 16).

Figure 16. Selecting a target volume

Notice that some of the volumes came with a stop icon. These volumes failed the requirements check set in Figure 12, that is, they have less than 1024 Mbytes of free space. And selecting these volumes will display the correct error message.

Next, click on the home icon on the left side of the volume list. Then click on the Continue button to display the Standard Install panel. Now click on the Customize button to switch to the Custom Install panel (Figure 17). The panel displays a list of each payload found in the package. If you highlight each payload, you get its description displayed on the field below that list.

Figure 17. Selecting a payload

Finally, with both payloads selected, click on the Install button on that panel. The Installer switches to a progress panel, which displays each stage of the installation. It then displays a last panel stating the results of the installation. For a final check, go to each of the following paths on your home directory.

   ~/Library/Application Support/BBEdit/Menu Scripts/
   ~/Library/Application Support/BBEdit/Scripts

You should find the scripts listed in Figure 8 installed in these directories.

Let's Add A Face

We will now localize our working package for two regions: English and French. Our package will have a different panel image and text for each region. We will then test our package to see the results.

First, arrange the localized files as shown in Figure 18. Here, we group each file in terms of target regions. Those localized for English go into the directory labeled english and those for French into the directory francais. Grouping the files keeps them within reach, as well as minimizes confusion.

Figure 18. Arranging the localized files

Next, choose Edit Interface from the Project menu to display the Interface Editor. Click on the '+' button to display the region dialog (Figure 19). To add the French region, enter the initials fr onto the provided field. You can also do the same by clicking on the pop-down button and choosing fr from the menu.

Figure 19. Adding a French region

Adding the background image

The first panel displayed by the Interface Editor is the Background panel. To set the background image for the English region, choose en from the region drop-down menu. Click on the radio button File on the settings drawer. Click on the drop-down menu button and choose Relative from the menu. Enter the path to the image file on the field provided. For the Foobar project, that path will be foobar/english/demo_english.pdf. The editor then updates the panel as shown in Figure 20.

Figure 20. Adding a background image

To set the image for the French region, choose fr from the region drop-down menu. Use the same steps to select the image file. For the Foobar project, the image file will be in the path foobar/francais/demo_francais.pdf. The editor should display a stylized Eiffel tower (see Figure 22) as a result.

Save your changes and click on the Continue button to display the Welcome panel.

Adding the panel text

To add text to the Welcome panel, first choose en from the region pop-up menu. Again, click on the radio button File from the settings drawer. Then click on the drop-down menu button and choose the menu item Relative. Enter the following path in the field provided.

   foobar/english/Demo_Introduction.rtf

The editor then updates the panel as shown in Figure 21.

Figure 21. The Welcome panel (English)

To do the same for French, choose fr from the region pop-up menu. Follow the same steps, but enter the following path to the field.

   foobar/francais/Demo_Introduction.rtf

The editor then updates the panel as shown in Figure 22.

Figure 22. The Welcome panel (French)

Use the same steps to set the next two panels: ReadMe and License. The files for these panels are shown in Table 1. Notice that all the files are in rich-text format. The tool also supports HTML and plain-text file formats. It does not, however, support PDF, ODT, or Word formats at this time.

Table 1. List of localized files

For the last panel, Conclusion, click on the radio button Embedded from the settings drawer. This action enables the large text field on that panel. Type the following phrase on that field.

Restart BBEdit in order to use these scripts.

Choose fr from the region pop-up menu, and type the following phrase on the same field

Relancement BBEdit afin d'employer ces scrits.

Use the Format menu to set the font, color, and alignment of both phrases. Save your changes to all the panels when done.

Always use the same source of text for all regions in each panel. If you used an external file for the English region, do the same for the other regions. If you typed the text directly onto the French region, do the same thing for the other regions. The tool does not support different text sources for each panel. In fact, changing the text source for one region, e.g. from File to Embedded, removes the text source on the other regions.

Testing the localized interface

To test the package, first choose System Preferences from the Apple menu. Click on the International icon and then on the Language tab. Make sure that the first item on the list of languages is English.

Back on the PackageMaker tool, choose Build and Run from the Project menu. Save the package under the name Foobar Installer, replacing the older version. Once Installer opens the package, click on the Continue button to view the panels. They should all display the correct image and text for the English region. Choose Quit from the Installer menu when you are done.

Next, go back to the System Preferences window. Move the entry Francais to the top of the language list. Then follow the same steps to rebuild and run the installer package. You should now see all the panels displaying the correct image and text for the French region.

Closing Remarks

The PackageMaker tool continues to improve with every release. Its latest form has a simpler interface, making the tool easier to use. It also has better support for localized files and for external script files. The tool still has a number of issues, but these issues are likely to be resolved in future versions.

Next time, we will learn how to use the tool to prepare applications for delivery. We will also learn how to select payloads based on target conditions and how to handle downgrades.

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


JC is a freelance engineering writer who lives happily in North Vancouver, British Columbia. He divides his time between writing technical articles, and teaching origami at his district's public library. He can be reached at anarakisware@gmail.com.

 
AAPL
$99.02
Apple Inc.
+1.35
MSFT
$43.97
Microsoft Corpora
-0.53
GOOG
$590.60
Google Inc.
+1.58

MacTech Search:
Community Search:

Software Updates via MacUpdate

OS X Yosemite Wallpaper 1.0 - Desktop im...
OS X Yosemite Wallpaper is the gorgeous new background image for Apple's upcoming OS X 10.10 Yosemite. This wallpaper is available for all screen resolutions with a source file that measures 5,418... Read more
Acorn 4.4 - Bitmap image editor. (Demo)
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Bartender 1.2.20 - Organize your menu ba...
Bartender lets you organize your menu bar apps. Features: Lets you tidy your menu bar apps how you want. See your menu bar apps when you want. Hide the apps you need to run, but do not need to... Read more
TotalFinder 1.6.2 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Tab-based... Read more
Vienna 3.0.0 RC 2 :be5265e: - RSS and At...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
VLC Media Player 2.1.5 - Popular multime...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more
Default Folder X 4.6.7 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more
TinkerTool 5.3 - Expanded preference set...
TinkerTool is an application that gives you access to additional preference settings Apple has built into Mac OS X. This allows to activate hidden features in the operating system and in some of the... Read more
Audio Hijack Pro 2.11.0 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Intermission 1.1.1 - Pause and rewind li...
Intermission allows you to pause and rewind live audio from any application on your Mac. Intermission will buffer up to 3 hours of audio, allowing users to skip through any assortment of audio... Read more

Latest Forum Discussions

See All

Traps n’ Gemstones Review
Traps n’ Gemstones Review By Campbell Bird on July 28th, 2014 Our Rating: :: CASTLEVANIA JONESUniversal App - Designed for iPhone and iPad Fight mummies, dig tunnels, and ride a runaway minecart to discover ancient secrets in this... | Read more »
The Phantom PI Mission Apparition Review
The Phantom PI Mission Apparition Review By Jordan Minor on July 28th, 2014 Our Rating: :: GHOSTS BUSTEDUniversal App - Designed for iPhone and iPad The Phantom PI is an exceedingly clever and well-crafted adventure game.   | Read more »
More Stubies Are Coming Your Way in a Ne...
More Stubies Are Coming Your Way in a New Update Posted by Jessica Fisher on July 28th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
The Great Prank War Review
The Great Prank War Review By Nadia Oxford on July 28th, 2014 Our Rating: :: PRANKING IS SERIOUS BUSINESSUniversal App - Designed for iPhone and iPad Though short, The Great Prank War offers an interesting and fun mix of action and... | Read more »
Marvel Contest of Champions Announced at...
Marvel Contest of Champions Announced at Comic-Con Posted by Jennifer Allen on July 28th, 2014 [ permalink ] Announced over the weekend at San Diego Comic-Con was the fairly exciting looking Marvel Contest of Champions. | Read more »
Teenage Mutant Ninja Turtles Review
Teenage Mutant Ninja Turtles Review By Jennifer Allen on July 28th, 2014 Our Rating: :: DULL SWIPINGUniversal App - Designed for iPhone and iPad The pizza power is weak when it comes to this Teenage Mutant Ninja Turtles game.   | Read more »
Exploration Focused Puzzle Game Beatbudd...
Exploration Focused Puzzle Game Beatbuddy Set to Make Transition from PC to iOS this September Posted by Jennifer Allen on July 28th, 2014 [ permalink ] | Read more »
PlanetHD
PlanetHD By Nadia Oxford on July 28th, 2014 Our Rating: :: SPACE MADNESSUniversal App - Designed for iPhone and iPad PlanetHD will keep players busy for a while, though its unpredictable physics are a handful to deal with.   | Read more »
This Week at 148Apps: July 21-25, 2014
Another Week of Expert App Reviews   At 148Apps, we help you sort through the great ocean of apps to find the ones we think you’ll like and the ones you’ll need. Our top picks become Editor’s Choice, our stamp of approval for apps with that little... | Read more »
Reddme for iPhone - The Reddit Client (...
Reddme for iPhone - The Reddit Client 1.0 Device: iOS iPhone Category: News Price: $.99, Version: 1.0 (iTunes) Description: Reddme for iPhone is an iOS 7-optimized Reddit client that offers a refreshing new way to experience Reddit... | Read more »

Price Scanner via MacPrices.net

13-inch 2.5GHz MacBook Pro on sale for $1099,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $1099.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more
Roundup of Apple refurbished MacBook Pros, th...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available for up to $400 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. Their prices... Read more
Record Mac Shipments In Q2/14 Confound Analys...
A Seeking Alpha Trefis commentary notes that Apple’s fiscal Q3 2014 results released July 22, beat market predictions on earnings, although revenues were slightly lower than anticipated. Apple’s Mac’... Read more
Intel To Launch Core M Silicon For Use In Not...
Digitimes’ Monica Chen and Joseph Tsai, report that Intel will launch 14nm-based Core M series processors specifically for use in fanless notebook/tablet 2-in-1 models in Q4 2014, with many models to... 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
iMacs on sale for $150 off MSRP, $250 off for...
Best Buy has iMacs on sale for up to $160 off MSRP for a limited time. Choose free home shipping or free instant local store pickup (if available). Prices are valid for online orders only, in-store... Read more
Mac minis on sale for $100 off MSRP, starting...
Best Buy has Mac minis on sale for $100 off MSRP. Choose free shipping or free instant local store pickup. Prices are for online orders only, in-store prices may vary: 2.5GHz Mac mini: $499.99 2.3GHz... Read more
Global Tablet Market Grows 11% in Q2/14 Notwi...
Worldwide tablet sales grew 11.0 percent year over year in the second quarter of 2014, with shipments reaching 49.3 million units according to preliminary data from the International Data Corporation... Read more
New iPhone 6 Models to Have Staggered Release...
Digitimes’ Cage Chao and Steve Shen report that according to unnamed sources in Apple’s upstream iPhone supply chain, the new 5.5-inch iPhone will be released several months later than the new 4.7-... Read more
New iOS App Helps People Feel Good About thei...
Mobile shoppers looking for big savings at their favorite stores can turn to the Goodshop app, a new iOS app with the latest coupons and deals at more than 5,000 online stores. In addition to being a... Read more

Jobs Board

Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full 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
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring 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
*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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.