TechNote (Archived)

Considerations for creating a Macintosh projector bundle

Overview

Director MX treats Macintosh OS X and "Classic MacOS" (MacOS 8.6 - 9.x) as separate platforms, requiring separate executables. Many developers have asked if there is a way to combine the two versions of their product into a single app that can be launched on either MacOS X or Classic MacOS; if you only need to target MacOS 9.x and later, packages and bundles provide the mechanism you need. This TechNote is intended as a brief introduction to putting together a Macintosh cross-platform (Macintosh OS X and OS 9), bundled projector.

Original content for this TechNote was provided by Darryl Trujillo, Director Development Engineer.

The following downloadable file contains a sample Director movie and an example bundle described further in this TechNote.

Download the Macintosh sit file (3.7 mb)

Packages

Packages were introduced with Macintosh OS 9.0 as a way to simplify application folder layout. A package is a folder hierarchy that closely resembles the usual application folder (containing app, shared libs, support files etc.), but to the casual user it looks like an application: double-click the package and the app inside is launched.

Inside a Package is a Contents folder and an alias to the actual application. For example, a packaged application "foo" might look like this:

foo.app ÂÂ Contents foo fooLib foo.alias

where the actual application "foo", along with its support library "fooLib", live inside a folder named Contents, which itself is placed in the package folder "foo.app". The package folder also contains an alias to the application.

Creating a package is as simple as creating the folders and dragging the pieces into place. Once everything is put together, the outermost folder will take on a custom folder icon with a little parcel in it. You can toggle your package open and closed by right-clicking (control-clicking) the package and selecting "hide package contents" or "show package contents". When contents are shown you get the folder with parcel and double-clicking opens the folder; when contents are hidden the folder takes on the application's icon and double-clicking launches the application.

Bundles

Macintosh OS X bundles take the package idea and add a lot more features, including support for multiple languages and multiple platforms in a single bundle. Bundles were designed to be backwardly compatible with packages under OS 9, so we can create a single bundle that contains code for OS 9 and OS X.

Bundles are laid out like packages, but with a few more items, including an XML file describing the contents. If we ported our"foo" example from OS 9 and created a bundle, it would look like this:

foo.app ÂÂ Contents Info.plist Pkginfo ÂÂÂ MacOS foo fooLib foo.alias

where "foo" and"fooLib" have been moved down into a folder named "MacOS", and two new files, Info.plist and Pkginfo, have been added to the Contents folder.

Pkginfo is a text file containing the type and creator info for the bundle. If our app had a creator type of 'foo!', the contents of Pkginfo would be "APPLfoo!" exactly.

Info.plist is the file that contains the XML property list describing the bundle. It also contains type/creator info, along with version data, icon and file associations, and the name of the executable (which eliminates the need for an alias). You can create this with a text editor, or using Apple's "Property List Editor," available on the Macintosh OS X Tools disk.

In OS X double-clicking a bundle always launches the app. To view the contents, right-click (control-click) the bundle and select "show bundle contents." Most applications in OS X are bundles.

It may be easier to view the example file as a set of folders in order to follow the discussion in this TechNote. To view the bundle as a set of folders follow the steps below.

To view a bundle as a set of folders:

1	Highlight the "foo" application icon and choose "show Info".
2	Choose "Name and Extension" from the drop-down list box.
3	Remove the ".app" extension from the filename in the File system name field.
4	Close the window and click "OK" when prompted.

Note: The steps above are only recommended for viewing the file hierarchy of the downloadable sample file used in this TechNote. Changing the extension names of bundles and packages is not recommended and may cause the applications you are changing to fail.

For more specific information about bundles, refer to Core Foundation Bundle Services on the Apple developer website.

Projectors

You can wrap a bundle around any simple CFM-based executable, including a projector. Standard projectors don't work from within bundles, though; when shared libraries are all packed into the same file, as they are with standard projectors, launching the bundle will result in a "library not found" error. Compressed projectors work okay, but they launch slowly, so it is assumed that most developers will be using Shockwave projectors in a "fast-start" layout, with libraries and xtras separate from the projector itself; that's the approach we'll use here. For more information about fast-start projectors, refer to "How to create a fast-start projector" (TechNote 14431).

Our example projector is a bundle containing stub projectors for Macintosh OS X and OS 9, both of which load the same movie"example.dir" which is also contained in the bundle. For more details about stub projectors, refer to "What is a stub projector?" (TechNote 13530). Example.dir is a simple movie with a text sprite and a vector shape sprite that slide across the stage; the text sprite uses an embedded font.

If we created a Macintosh OS X only bundle with this arrangement, it would look like this:

The bundle has a Contents folder, which contains the movie"Example.dir", property list "Info.plist", package info file"Pkginfo", and a MacOS folder containing the MacOS X executables. The MacOS folder contains our stub projector "stubX", shared libraries "DP", "IMLLib", "MacromediaRuntimeLib" and "ProjLib", along with an Xtras folder containing MacOS X versions of the Xtras required by Example.dir.

The stub projector (from "stub.dir" provided with the example) contains a single behavior that initiates a "go to movie" command. Since the movie is located in the stub's parent directory, we load it as "::example.dir". We named it "stubX" to distinguish it from the MacOS 9 version.

A Macintosh OS 9 package version of this projector would look similar. Since we know we're going to combine this with the MacOS X bundle, we'll start right off placing the MacOS 9 bits into a"ClassicMacOS" folder, and get something like this:

There are no Info.plist or Pkginfo files, but we do have an alias to the executable, which is named "stub9". We created stub9 from the same "stub.dir" as the MacOS X version, but when creating the projector we chose "Classic MacOS" as a target. Make sure you strip all Xtras from the stub before creating the projector. You may need to re-create or fix the alias when moving the bundle to another disk; if you're mastering a CD with this content, you may want to create your master from a disk partition image of your CD, so the volume name will be the same.

The MacOS 9 versions of the shared libraries and Xtras are available in the "Classic MacOS" folder inside the "Macromedia Director MX" application folder.

Now we can combine the package and the bundle into one. The complete bundle looks like this, two copies of the stub projector, libraries and Xtras; one copy of the actual content:

Getting this on a CD

Once the bundle has been created it is nearly ready to be transferred to a CD. A few things must be done prior to this however, in order to insure the bundle works properly. The "stub9" alias at the root will have to created from a disk image, otherwise the alias will point to the original hard drive location of the original projector. Use the OS X application Disk Copy to create a disk image to be burned to the CD. Once a disk image is created, create an alias to the OS 9 projector and place the alias at the same level as the bundle (Refer to the image above). You will also need add the .app extension to the bundle file after the alias has been created and moved to its proper location.