CL offers this page hesitantly; I'm still not sure it's a style to be promoted. I welcome reactions.

---

The section, "How to write the main.tcl for a starkit" in "Starkit - How To's", presents a coherent and correct model for organizing starkit-oriented Tcl coding. Jean-Claude highlights there construction which allows the same source to be run unwrapped, within a starkit, within a starpack, and so on. It's important to understand the benefit of this. While I don't have a satisfying way yet to express it, the idea is something like this: to make the best advantage of existing software and experience in Tcl development, projects need to look "physically" as they always have: a main.tcl which sources other local Tcl scripts. If the project can be maintained either as a conventional pure-Tcl bundle, or a Starkit VFS, then it'll enjoy the advantages of both modes.

"How to write ..." aims at package-structured projects. As desirable as "packagization" is, this page presents an alternative, "package-less", outline for code maintenance. This makes startup more clumsy, as starkit automatically sets up the right search path for the packages it encapsulates. Once past the verbose work-around of the switch seen below, though, the source file hierarchy is easier to recognize as invariant across the different execution modes. This is a particular advantage for other sources, such as *.gif-s or so on. It also has the trivial advantage that it doesn't expose the "magic suffix" myapp.vfs in the code to be maintained. Moreover, it is, I believe, the most direct answer to the questions raised in one particular thread [1] (which itself invites more commentary--perhaps later) in comp.lang.tcl.

This is the construction: write these four source files:

    ########
    # This is make_example.sh
    ########
    DEMONSTRATION=/tmp/demo$$
    SRCDIR=example.vfs/lib/app-example

    rm -rf example.vfs
    sdx qwrap example.tcl
    sdx unwrap example.kit
    cp lib1.tcl $SRCDIR
    mkdir $SRCDIR/subdir
    cp subdir/lib2.tcl $SRCDIR/subdir
    sdx wrap example.kit

        # By removing all traces of the VFS image, and relocating
        # to a fresh (empty) directory, we demonstrate that the
        # sourc-ing is indeed working with the scripts packaged
        # within example.kit.  The larger significance is that deploy-
        # ment demands no "installation"; example.kit encapsulates
        # all the application-specific stuff necessary, in a single
        # file, while allowing development to be structured in an
        # arbitrary tree.
    rm -rf example.vfs
    mkdir $DEMONSTRATION
    cp example.kit $DEMONSTRATION
    cd $DEMONSTRATION

    tclkit example.kit

.

    ########
    # This is example.tcl.
    ########
    puts "Here I am."

    package require starkit
    switch [starkit::startup] {
        unwrapped {
            set offset ""
        }
        sourced {
            set offset [file join lib app-example]
        }
    }

    set srcdir [file join $starkit::topdir $offset]

    set lib1 [file join $srcdir lib1.tcl]
    set lib2 [file join $srcdir subdir lib2.tcl]

    source $lib1
    source $lib2

.

    ########
    # This is lib1.tcl
    ########
    puts "I made it!  This is lib1.tcl."

.

    ########
    # This is subdir/lib2.tcl
    ########
    puts "This is lib2.tcl."

If you now run

    tclkit example.tcl

OR

    sh make_example.sh

the output is the same:

    Here I am.
    I made it!  This is lib1.tcl.
    This is lib2.tcl.

[Why is this here rather than within the Starkit Wiki [2]? The benefit is to subordinate Starkit details to a focus on Tcl coding and the development process.]

[... much more to say ...]

[which-starkit-name problem]

[Fix up

    tclkit  << HERE
    source example.tcl
    HERE

]

How to create my first Starpack

Attractive diagrams make "Anatomy of a starkit" [3] particularly edifying.

---