Deliver Stand-alone Applications with MacOS X

Like the MS-Windows and MacOS 9 version of VisualWorks 7.0, this
implementation supports combining a VM and an image to form a stand-alone
MacOS X application.  The following paragraphs describe how this is done.

1	Smalltalk preliminaries

When preparing a runtime image using RuntimePackager, you should
follow these hints:

 - disable command line processing
 - enable delivery at least for 'Operating Systems' 'Mac' and 'Unix',
 - at least enable support for 'UI Looks' 'Mac'
 - ensure that all classes of parcel GHMacOSXLookFeel are marked as
   classes to be kept, especially when preparing the image on a platform
   other than Mac OS X.
 - make sure that all 'Unix*' classes, and classes of parcel 'MacOSXBasic'
   are to be kept.

Test the image thoroughly on all platforms you want to deliver, before
performing the next step.  The image should be named 'resource.im' if used
in a MacOS X application.

2	MacOS X Application Packaging

MacOS X has its own way of combining an executable and several resources
to an application.  The following description is short and may not touch
all available features of this process, but it should give you enough
background to move on from there.

2.1	Some background

Each MacOS X application is, from a Unix point of view, a directory with a
certain structure.  The directory's name must have the extension '.app',
and the structure has to be as follows (using visual.app as an example):

    visual.app/ 				"this name only visible from a shell"
        Contents/
            PkgInfo				"file containing type/creator bits as in MacOS 9"
            Info.plist				"XML file containg all package infos of this application"
            MacOS/
                visual				"the Unix type executable"
            Resources/
                MainIcons.icns		"the icons for the application"
                ImageIcons.icns		"the icons for image files"
                herald.tiff			"the herald screen graphics"
                resource.im		"place and name for an image bundled with the VM"
                English.lproj/		"place for language dependent resources for menus etc."
                    InfoPlist.strings	"Unicode encoded file with language dependent strings"
                    <other files>

Except for the Icon files, all files can only be replaced, but not renamed.

Icons are used for Finder display of files. You can modify the icons using
the 'IconComposer' application included in the Apple DeveloperTools distribution.

The splash screen graphics can be replaced with a Tiff-file with exactly this name.

The 'PkgInfo' file conatins just 8 characters, which, for VisualWorks 7.0, are:

    APPLHPS7

For your application, the last four characters have to be replaced by your
creator code, which should be registered with Apple and be unique.

The file 'Info.plist' is in XML format, and can be edited with a normal
text editor, or with the PropertyListEditor included in the Developer Tools.  
Several facts about the application are collected in this
file, like which icon file is used for the application, what document
types are to be recognized, etc.  The XML structure describes a dictionary
which has to be adapted for each application.  The following lists the
most important key-value pairs, which you have to edit:

    CFBundleTypeExtension	- 	an array of strings, VisualWorks => <string>.im</string>
    CFBundleTypeIconFile  	-	name of the documents icon file in the /Resource directory
							WITHOUT the '.icns' extension,
							VisualWorks => <string>ImageIcons</string>
    CFBundleTypeOSTypes	-	array of type descriptors of a document, (in our case for image files)
							VisualWorks =>
								<array>
									<string>HPS7</string>
								</array>

    CFBundleExecutable		-	name of the executable in Contents/MacOS
							VisualWorks =>
								<string>visual</string>

    CFBundleIconFile			-	name of the applications icon file in the
							/Resource directory WITHOUT the '.icns' extension, 
							VisualWorks =>
								<string>MainIcons</string>

    CFBundleIdentifier		 -	name of the entry for a preferences dictionary
							in the UserDefaults database
							VisualWorks =>
								<string>com.cincom.vw7.0</string>

    CFBundleSignature		-	creator type of this application
							VisualWorks =>
								<string>HPS7</string>
							Remember to adapt this file, if you add or
							replace icon files with different names.

The last file you have to edit is the InfoPlist.strings file in each of
the *.lproj directories of the Resource folder.  For each language, the
strings in this file can be adapted.  This file is a Unicode text file,
and must be edited with an Unicode-aware editor, e.g. the TextEdit or PropertyListEditor
application that comes with MacOS X (PropertyListEditor included in DeveloperTools).  
The file's first entry initially ensures that the applications menu has only the menu item 'VisualWorks'.

2.2	How to do it

To combine a VisualWorks VM and your 'resource.im' to form a MacOS X
application, begin by opening the Terminal application because you need
to execute tasks from a command line; the Finder won't work.

 i. Make a copy of the visual.app/ directory:

	user% cp -R visual.app myApp.appToBe

    Remove all unnecessary UnixVMs from this copy:

	user% rm myApp.appToBe/Contents/MacOS/vwmacxdbg
	user% rm myApp.appToBe/Contents/MacOS/vwmacxast
	user% rm myApp.appToBe/Contents/MacOS/vwmacx

 ii. Copy your image into the 'myApp.appToBe/Contents/Resource' directory:

        user% cp resource.im myApp.appToBe/Contents/Resources

 iii. Edit the file 'myApp.appToBe/Contents/PkgInfo' to make your application
    unique.  Enter your creator code as the last four characters of this file.

 iv.  Remove or change the following entries in the file 
     'myApp.appToBe/Contents/Info.plist'. Any occurrence of 'HPS7'
     should be removed from this file.
		CFBundleTypeOSTypes
		CFBundleSignature

 v.  Rename the directory	'myApp.appToBe' to 'myApp.app':

        user% mv myApp.appToBe myApp.app

You can now start up your application with a double-click.  It is just
missing some unique Icon(s).  After you have replaced file MainIcons.icns
with your version, the application will show up as a unique MacOS X
application in the Finder. If you edited myApp/Contents/Info.plist, you
might have to logout and login again to make the Finder read your new
specifications.

Note that this version does not handle documents dropped on such
applications correctly.

3	Creating and using a Userprimitive VM

As on other platforms, it is perfectly possible to compile a customized VM,
enhanced with user defined primitives. Directory bin/macx/userprim contains
all necessary files. The compilation using make can only be performed from a
Terminal, as on other Unix platforms.
Lets assume you use the makefile unchanged, then it will compile an executable
called 'visualUser'. Now, this is a Unix executable, the Finder won't recognize it as
an application yet. How can you use it?
 i.	start your image from the Terminal like this:
		user% visualUser myImage.im

 ii.	copy 'visualUser' into your application directory 'myApp.app' (see chapter 2.2):
		user% cp visualUser myApp.app/Contents/MacOS/visual

	and start your application by double-clicking.

Cincom / Georg Heeg May 2002