How to Build Tcl/Tk Application Bundles: the Mac Way

Tcl/Tk on Mac OS X does an excellent job of integrating the command-line Tcl/Tk environment with the Aqua interface. Tcl scripts can be run from the Terminal or sourced from the Wish application that ships with Tcl/Tk.

As convenient as these tools are, however, it is still not the same as clicking on a distinct Mac application with its own name, its own icon, and so forth. When a Tcl script is running under the Wish application, a generic "Wish" application name shows up in the menu bar. Additionally, given that many Tcl/Tk applications are in fact a whole suite of scripts, finding the correct script that will start the entire application can sometimes be cumbersome.

Wish: A Wrapper for Standalone Tcl/Tk Aqua Applications

It is, however, possible to build a double-clickable Tcl/Tk Aqua application bundle that will run under its own name in the Aqua environment. The Wish application is not just a tool for launching scripts; it can also serve as a wrapper for standalone applications. Wish, like all GUI Aqua applications, is actually a file directory diguised as a single file with its own icon. One version of Wish includes the Tcl/Tk framework libraries, and can run on Mac OS X systems without a separate installation of Tcl/Tk; this facilitates the delivery of your Tk Aqua application to end users. For our example here, we will use Visual Tcl, a GUI-building application written in Tcl/Tk.

The first thing to do is to build a standalone Wish Shell application; see the Tcl/Tk source code for details. Then, right-click on the application and choose "Show Package Contents." You will see a "Contents" folder; navigate into this folder and you will see the "MacOS" and "Resources" directory.

The next thing to do is to navigate to the source code folder for Visual Tcl, which you downloaded from the Visual Tcl website. Create a script called "AppMain.tcl" that consists of the following code:

if {[string first "-psn" [lindex $argv 0]] == 0} { set argv [lrange $argv 1 end]}

console show

if [catch {source [file join [file dirname [info script]] vtcl.tcl]}] { puts $errorInfo}

AppMain.tcl is the first file that Wish will look for when it launches; this file initializes the rest of the application. The code in this brief script is important, so let's step through it.

The first code snippet does several things. First, it connects Wish with the Aqua/Carbon process manager ("psn" means "process serial number"), and allows drag-and-drop launching of your application ("argv" refers to the file names that are dropped on the application icon).

The next snippet launches Wish's built-in console for error output. This is useful as you refine your application. If you want to turn the console off when you ship the final version of your application, just comment out the line (using the # symbol at the line's beginning).

The final snippet loads the main Visual Tcl script, vtcl.tcl, into the Wish event loop, and begins running the program itself. The "errorInfo" variable suppresses error output and keeps the application from crashing.

Once you have created the main script, then rename the folder where all the Visual Tcl files and directories are to "Scripts." Then, copy the "Scripts" folder into the "Resources" directory of the Wish Shell application.

Customizing the Wish Shell

Once you have done this, you are almost finished, but there are a couple of more steps to take:

• Look again in the Resources directory. You should find a file called "Wish.icns." This is the generic Wish Shell application icon; "icns" is the Macintosh icon file format. See Apple's current documentation on creating an icon file. (This tutorial assumes you have installed Xcode, which is available from the Mac App Store) Find another graphic image to import, then save the graphic as an icon file ("title.icns") in the "Resources" directory of the Visual Tcl app bundle. You may want to test the application at this point by double-clicking on the icon (find the application icon in the Finder; don't try to click on the "icns" file inside the resources directory). If it launches, then the hard part is over and you are almost finished.
  
  

• Next, navigate up one level from the Resources directory. You should find a file called "Info.plist." This is an XML file that includes a variety of information about the application bundle, including the name of the executable file, the name of the application bundle itself, and the name of the icon file. Find the line marked "CFBundleIcon" and change the name from "Wish.icns" to "title.icns" or whatever name you choose. If you want to change the application name, then find the line "CFBundleName" and change the name from "Wish" to whatever you choose, such as "Visual Tcl OSX." Save and close the file, and then close the entire application directory. Don't forget to rename the application iself in the Finder with the new name you provided in the "Info.plist" file, just as if you were renaming any other file or folder.
  
  

Finally, if you have any supporting libraries that must be included in the bundle, such as Tclapplescript, go up to the top-level "contents" directory and create a folder called "lib." Wish will look here for any supporting libraries required by your application (indicated by a "package require" statement in your scripts). You can copy these libraries directly from the Tcl/Tk Aqua installation in /LIbrary/Tcl; this is a very convenient approach.

Starpacks

On platforms other than Mac OS X, starpacks are the standard way to deploy standalone Tcl/Tk executables. It is possible to do this on OS X as well. Here are the basic instructions:

• Wrap your scripts and extensions in a starkit as on other platforms, then wrap the starkit in the Aqua-specific tclkit runtime, which can be downloaded here.

• Make sure the Aqua starkit is executable by running the appropriate chmod command on it.

• Place the starkit in the Contents/MacOS directory of your application bundle, and edit the info.plist file to specify the name of the starkit as the bundle's executable.

• You will still need to include the application icon in the Contents/Resources directory, but other items--such as the AppMain.tcl script and similar items--are already included in the starpack and should not be placed in the Resources directory.

You Have an Application Bundle

If you rename the application in the Finder, the new icon should appear. If it does not, you may want to relaunch the Finder, as sometimes it does not immediately see changes to application bundles. Once you relaunch the Finder (from the Force Quit menu), your Visual Tcl application bundle (with its new name and icon) should be visible. Try double-clicking on the application bundle; if everything has been done correctly, the new application will launch with its own icon visible in the Dock, and with its own application name (Visual Tcl OSX, not Wish) in the menu.

An increasing number of popular Tcl/Tk applications, including WaveSurfer and TkChat, are distributed in this fashion. The overall smoothness of the packaging process can be attributed to the excellent work of the Tcl/Tk Aqua team.