Creating a Shared Starkit

Starkits can be used to create modules that are shared by other applications. For example, the kitten.kit Starkit contains about 50 popular extensions, and several of them are binary extensions. It is over 4 MB in size, and so it is a great candidate for sharing. You can find kitten.kit on the CD-ROM or in the Starkit archive. By organizing each shared module into a Starkit with the appropriate structure, it is a simple matter to share them.

Whenever a Starkit is sourced, Tclkit mounts its VFS and looks for its main.tcl file. This is true for shared Starkits as well as the main Starkit of an application. If main.tcl calls starkit::startup, then the lib directory in the VFS is automatically added to the auto_path. Any libraries organized under lib will be automatically accessible to the application that sourced the Starkit.

You can add a little logic to make your package behave differently if it is run as the main Starkit or sourced into another application. For example, this is done in the tcllib Starkit, which starts a stand-alone Wiki that describes the Standard Tcl Library APIs if run as its own Starkit. Otherwise it just sets up tcllib to be shared by the main application. Example 22-11 shows the main.tcl of tcllib.kit. It has to explicitly add the tcllib directory to the auto_path because it has both a lib and tcllib directory in its VFS:

Example 22-11 The Standard Tcl Library Starkit main.tcl file

package require starkit
if {[starkit::startup] eq "starkit"} {
   # Do application startup
   package require app-tcllib
} else {
   # Set up to be used as a library
   set vfsroot [file dirname [file normalize [info script]]]
   lappend auto_path [file join $vfsroot tcllib]
}

Another side effect of starkit::startup is to set starkit::topdir. However, this variable is only set once. If you source other Starkits that call starkit::startup, then the starkit::topdir value is not disturbed.

This behavior changed in Tclkit 8.4.2. In earlier versions, starkit::topdir was set by each Starkit, so you had to worry about saving its value if you loaded other Starkits. If you source tcllib.kit and cannot package require its packages, check its main.tcl. If it uses starkit::topdir in the non-Starkit case, then it is an older version. Simply unwrap it, make its main.tcl look like Example 22-11, and wrap it back up to fix the problem.

The starkit::startup procedure determines the environment of the application by making a series of tests against the script environment. Its return value helps your main.tcl script distinguish between starting out as the main Starkit, or being loaded into another Starkit as a library. Table 22-1 lists the return values of the starkit::startup procedure in the order they are checked:

Table 22-1. Return values of the starkit::startup procedure

starpack	The Starkit was bundled with tclkit to make a Starpack.
starkit	The Starkit was run by itself.
unwrapped	The Starkit was run out of its unpacked vfs directory.
tclhttpd	The Starkit was sourced into TclHttpd.
plugin	The Starkit was sourced in the browser plugin.
service	The Starkit was run in an NT service.
sourced	The Starkit was sourced by another Starkit.

The easiest way to organize your shared Starkits is to put them into the same directory. Example 22-12 shows how the TclHttpd Starkit is modified to load the tcllib Starkit from the same directory.

Example 22-12 The main program for TclHttpd Starkit, version 3

package require starkit
starkit::startup
set dir [file dirname $starkit::topdir]
if {![file exists [file join $dir tcllib.kit]]} {
   puts stderr "Please install tcllib.kit in $dir"
   exit 1
}
source [file join $dir tcllib.kit]
source [file join $starkit::topdir tclhttpd/bin/httpd.tcl]