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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Together 3.7 - Store and organize all of...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Features Smart storage. With simple drag-and-drop... Read more
EtreCheck 3.1.4 - 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
Postbox 5.0.9 - Powerful and flexible em...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
DiskCatalogMaker 6.5.16 - Catalog your d...
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... Read more
TrailRunner 3.8.827 - Route planning for...
TrailRunner is the perfect companion for runners, bikers, hikers, and all people wandering under the sky. Plan routes on a geographical map. Import GPS or workout recordings and journalize your... Read more
VueScan 9.5.61 - 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
Postbox 5.0.9 - Powerful and flexible em...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
VueScan 9.5.61 - 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
DiskCatalogMaker 6.5.16 - Catalog your d...
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... Read more
TrailRunner 3.8.827 - Route planning for...
TrailRunner is the perfect companion for runners, bikers, hikers, and all people wandering under the sky. Plan routes on a geographical map. Import GPS or workout recordings and journalize your... Read more

Latest Forum Discussions

See All

Great zombie games in the spirit of Dead...
Dead Rising 4 arrives tomorrow, giving enthusiasts a fresh chance to take selfies with zombies and get up to other ridiculous end-of-the-world shenanigans. To really get into the spirit of things, we've gone and gathered the best zombie games that... | Read more »
Amateur Surgeon 4 Guide: Advanced tips a...
Amateur Surgeon 4 is still tackling the competition at the top of the App Store charts, so if you haven't tried it out yet, you should probably do that right away. If you've been at it for a while, though, perhaps you're ready to start expanding... | Read more »
Amateur Surgeon 4 Guide: Become the worl...
It's time to wield your trusty pizza cutter again, as Amateur Surgeon has returned with a whole fresh set of challenges (and some old, familiar ones, too). Starting anew isn't easy, especially when all you have at your disposal is a lighter, the... | Read more »
Le Parker: Sous Chef Extraordinaire (Ga...
Le Parker: Sous Chef Extraordinaire 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »
Telltale Games really is working on a Gu...
Telltale Games' next episodic adventure is indeed Guardians of the Galaxy. A document tied to the voice actors strike suggested that the project was in the work, but now we have direct confirmation following an announcement at the Game Awards that... | Read more »
Amateur Surgeon returns to iOS and Andro...
Amateur Surgeon and its two sequels disappeared from the App Store some time and it was sad days for all. But now, just in time for the holidays, the Adult Swim favorite makes its joyous return in the shape of Amateur Surgeon 4, a remake with... | Read more »
The best board games on mobile
Sometimes you need to ditch all of the high speed, high action games in favor of something a little more traditional. If you don't feel like parting ways from your mobile device, though, there are still plenty of ways to get that old-school fix.... | Read more »
The best Facebook Messenger Instant Game...
Facebook's new Instant Games is now here, meaning you can play games with your friends directly via Facebook. It's a fun new way to connect with friends, of course, but it's also proving to be a solid gaming experience in its own right, with a... | Read more »
You can now play game's on Facebook...
Facebook launched its new Instant Games platform in an exciting new attempt to engage its user base. As a result, you can now play a number of different games directly through Facebook Messenger. All of these games run with HTML5, meaning you play... | Read more »
Apollo Justice Ace Attorney (Games)
Apollo Justice Ace Attorney 1.00.00 Device: iOS Universal Category: Games Price: $.99, Version: 1.00.00 (iTunes) Description: Court Is Back In Session Star as rookie defense attorney, Apollo Justice, as he visits crime scenes,... | Read more »

Price Scanner via MacPrices.net

Monday roundup of Holiday Mac sales: Up to $3...
Take up to $300 off MSRP on the price of a new Apple Mac at B&H Photo today as part of their Holiday sale. Shipping is free, and B&H charges NY sales tax only. Touch Bar MacBook Pros are in... Read more
12-inch WiFi Apple iPad Pros on sale for up t...
B&H Photo has 12″ WiFi Apple iPad Pros on sale for up to $50 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 12″ Space Gray 32GB WiFi iPad Pro: $749 $50 off MSRP... Read more
9-inch Apple WiFi iPad Pros on sale for $20-$...
B&H Photo has 9.7″ Apple WiFi iPad Pros on sale for $20-$50 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 9″ Space Gray 256GB WiFi iPad Pro: $779.95 $20 off MSRP... Read more
Holiday sale: Apple MacBook Airs available fo...
B&H Photo has 13″ MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/128GB MacBook Air (MMGF2LL/A): $899 $100 off MSRP - 13″ 1.6GHz/... Read more
13-inch Silver Touch Bar MacBook Pro in stock...
Amazon has the new 2016 13″ 2.9GHz/256GB Silver Touch Bar MacBook Pro (MLVP2LL/A) in stock today and on sale for $1749 including free shipping. That’s $50 off MSRP, and it’s the lowest price... Read more
Parallels Toolbox 1.3 for Mac Offers 25 Singl...
Parallels has launched Parallels Toolbox 1.3 for Mac, an upgrade that adds five new utilities to the stand-alone application which was released in August and is available exclusively online at http... Read more
OWC Mercury Elite Pro Dual mini Ultra-Portabl...
OWC has introduced the new OWC Mercury Elite Pro Dual mini, a powerful yet ultra-portable dual-drive RAID solution. The new Mercury Elite Pro Dual mini packs phenomenal performance into a small... Read more
Clearance 13-inch Retina MacBook Pros availab...
B&H Photo has clearance 2015 13″ Retina Apple MacBook Pros available for up to $200 off original MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $... Read more
Roundup of 2016 13-inch 2.0GHz MacBook Pro sa...
B&H has the non-Touch Bar 13″ MacBook Pros in stock today for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (MLL42LL/A): $1449 $... Read more
New 13-inch 2.0GHz Space Gray MacBook Pro in...
Adorama has the new 13″ 2.0GHz Space Gray MacBook Pro (non-Touch Bar, MLL42LL/A) in stock for $1499 including a free 3-year AppleCare Protection Plan. Shipping is free, and Adorama charges sales tax... Read more

Jobs Board

Lead *Apple* Solutions Consultant - Apple (...
# Lead Apple Solutions Consultant Job Number: 53586123 Pittsburgh, Pennsylvania, United States Posted: Nov. 28, 2016 Weekly Hours: 40.00 **Job Summary** The Lead ASC Read more
*Apple* Retail - Multiple Positions- Plano,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions- Kansas...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions- Chicago...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Hardware Design Validation Engineer - *Apple...
The Apple Watch team is looking for a Hardware Design Validation Engineer. This person will be part of the Apple Watch hardware team with responsibilities for Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.