Using sdx to Bundle Applications

Sdx, which stands for Starkit Developer eXtension, is an application that you run from the Unix, Windows, or MacOS command line to create and manipulate Starkits. It is itself a Starkit, of course. The sdx application is on the CD-ROM, and you can find a link to it from the Starkit home page:

http://www.equi4.com/starkit/

Creating a Simple Starkit

Creating a Starkit amounts to creating a directory structure that contains the files you need, and then wrapping them up with sdx. Create files under kitname.vfs, and wrap them into the kitname.kit Starkit with:

sdx wrap kitname.kit

In simple cases, sdx will create the directory structure for you. For example, if you have a self-contained Tcl script called hello.tcl, then you can turn it into a Starkit like this:

sdx qwrap hello.tcl

The qwrap operation (i.e., "quick wrap") creates a new Starkit, hello.kit, that includes the original hello.tcl script organized into a virtual file system hierarchy with some additional support files. You run the Starkit like this:

tclkit hello.kit

On Unix systems you can also execute the Starkit directly. The file uses the #! syntax to specify that tclkit should run the file. On Windows, you can achieve the same effect by associating tclkit.exe with files that end in .kit.

Examining a Starkit

There are two ways to look at a Starkit. You can get a listing of the files with the sdx lsk operation, or you can use sdx unwrap to extract the files from the Starkit into a kitname.vfs directory. Example 22-2 shows the lsk output for hello.kit. The dates are in YY/MM/DD format:

Example 22-2 The output of sdx lsk hello.kit

hello.kit:
                       dir  lib/
        67  02/11/08 12:07  main.tcl
hello.kit/lib:
                       dir  app-hello/
hello.kit/lib/app-hello:
        43  02/11/08 12:10  hello.tcl
        72  02/11/08 12:07  pkgIndex.tcl

Standard Package Organization

The qwrap operation turns the hello.tcl script into the app-hello package. If necessary, sdx adds a package provide app-hello 1.0 command to the hello.tcl script. It also creates a short main.tcl script that initializes the Starkit system and invokes hello.tcl by doing a package require. Example 22-3 shows main.tcl:

Example 22-3 The main program of a Starkit

package require starkit
starkit::startup
package require app-hello

When you run the Starkit, its Metakit database is mounted into a Virtual File System that is visible to the Tcl application. Tclkit sources the main.tcl script it finds in the VFS. The starkit::startup procedure updates the auto_path to contain the Starkit's lib directory, so any packages stored there are available to the package mechanism. By convention, the application is put into a package with the name app-kitname. Example 22-4 shows the pkgIndex.tcl, which causes the package require app-hello command to source hello.tcl.

Example 22-4 The pkgIndex.tcl in a Starkit

package ifneeded app-hello 1.0 \
   [list source [file join $dir hello.tcl]]

The dir variable is set by the package mechanism to be the directory containing the pkgIndex.tcl file. That the lib directory happens to be inside the virtual file system is completely transparent to the package mechanism. The package mechanism is described in more detail in Chapter 12.

Creating a Starpack

A Starpack contains a copy of Tclkit and your Starkit. Use sdx to create Starpacks. The -runtime flag specifies which Tclkit application you want to merge with your Starkit. For example, to build a Windows Starpack out of our hello.tcl application:

sdx wrap hello.kit -runtime tclkit-win32.exe

To build a Starkit for Linux, use the appropriate runtime:

sdx wrap hello.kit -runtime tclkit-linux-x86

There are 4 variations of the Windows Tclkit. One option uses zlib to automatically compress Tclkit and the Metakit database. These have .upx in their name. The other creates a console-mode application that does not include Tk. These have -sh in their name. The smallest Tclkit, tclkit-win32-sh.upx.exe, is only 450 K. Even tclkit-win32.upx.exe is only 907 K, so you really can create complete applications that fit easily onto a floppy disk!

The auto-compress variation is also available on the Linux x86 builds as the tclkit-linux-x86.upx.bin runtime file. Check the Tclkit home page for the latest set of Tclkit builds:

http://www.equi4.com/tclkit