Anatomy of a starkit

(For full details about Starkits, see https://www.equi4.com/starkit.html)

A Starkit contains a small standard header, followed by binary data:

(the actual header is slightly different, this is a simplified version)

The Tclkit runtime is very similar, in this case the (large) header contains executable code:

(in both cases, the OS starts from the start of the while, while Metakit always reads from the end to locate its data)

A Starpack combines both of the above into a single file. It has the same executable header as Tclkit, with all data from both Metakit databases merged into one:

The startup sequence of a Starkit can be visualized as:

The Metakit database contains the equivalent of a directory tree, here is an example:

The following info was taken from http://mini.net/tcl/3463

There is an emerging standard for the internal directory structure of a scripted document. This standard is based on the experience gained from building a variety of Starkits and Starpacks.

The toplevel directory would contain

        doc/            contains any documentation
        lib/            comtains any libraries
        main.tcl        contains the starkit startup script

The toplevel main.tcl gets called on startup. It typically contains a line like the following

        package require starkit
        starkit::startup
        package require app-appname

The starkit::topdir variable can be used in your application when locating other directories within the starkit. It was also used to extend the auto_path variable with the lib directory.

Note also that the application code lives in the package app-appname , where appname is your application name. This package lives in the directory lib/app-appname. Inside this directory, you will need a pkgIndex.tcl file similar to the following (where $appVersion is the version of your application).

   package ifneeded app-appname $appVersion [list source [file join $dir appname.tcl]]

and appname.tcl will need to contain a line similar to the following

   package provide app-appname $appVersion

So, to summarise, a minimal scripted document will need

        appname.vfs/main.tcl
        appname.vfs/lib/app-appname/pkgIndex.tcl
        appname.vfs/lib/app-appname/appname.tcl

The rationale for separating the application code into a separate package is that it will make it easier to modularise code and combine starkits.

For example, the wikit scripted document [1] contains the following structure

        wikit.vfs/main.tcl
        wikit.vfs/doc/wikidoc.tkd
        wikit.vfs/lib/app-wikit
        wikit.vfs/lib/autoscroll
        wikit.vfs/lib/cgi
        wikit.vfs/lib/gbutton
        wikit.vfs/lib/wikit

Note the following:

• doc/wikidoc.tkd is the help wiki for the wikit application (see [2])
• the app-wikit application is just a wrapper around the wikit package
• the wikit package can be embedded in other applications (such as sdx :-)
• autoscroll, cgi, gbutton and wikit are packages used by the wikit application

OLDER NOTES

Here are some bits I will need to clean up and consolidate:

• http://mini.net/tcl/tclkit is a reference page on the Tcl'ers Wiki
• http://mini.net/tcl/25 is a reference page about SD's on that wiki
• http://mini.net/tcl/2920! lists a few more categorized references on that wiki

Some raw thoughts on what seems to be needed:

• what is a scripted doc
• explain 1-file, 2-file, N-file approaches
• prerequisites for creating them
• how to run/create on classic Mac
• adding packages (auto_path, extendPath)
• how shared libs work
• differences when running in sd (exec, pwd)
• the 1-file approach: custom tclkits
• how to construct them
• the N-file approach: e.g. kitten
• how to use such an additional file
• read-only vs. read-write SD's
• CGI issues, permissions, lock files
• how to develop in a wrap-ready way (myapp.vfs/...)
• how to use critcl pkgs in an SD