How to create my first Starpack

Purpose: define the steps for one to take to create their first starpack.

Read Steve Landers' paper - PDF: [1], HTML: [2].
Download a tclkit for your platform from e.g. http://www.equi4.com/tclkit/download.html. For Windows, download both the gui-version (tclkit-win32.upx.exe) and the command-line version (tclkitsh-win32.upx.exe). The command-line version is silent and does not produce pop-up screens, so it can be used to script the generation your executable. The gui-version should be used when you specify the run-time tool in the final step when you link your script, otherwise your application will be silent too ;-).
Download sdx, e.g. from http://www.equi4.com/pub/sk/sdx.kit
Assemble a starkit [3] based on the examples in the paper
Use sdx to make a starpack from this starkit.

You can even use your own application for the initial time through; "starkitting" is straightforward enough that people have been successful doing it for the first time even with applications which involve several auxiliary files, extensions (but only stubsified ones?), and so on.

I'll break this down a slightly different way:

Install tclkit and sdx so they're available in your PATH.

       On Unix, these may be installed as ''tclkit'' and ''sdx'', while
       on Windows, these are more likely installed as ''tclkit.exe'' and
       ''sdx.kit''.  On Unix, remember to change the permission modes of
       tclkit to be executable.

Put sdx.kit in your working directory.
Create example.tcl:

            package require Tk
            pack [button .b -text "That's all for now" -command exit]

Wrap:

Unix: tclkit sdx.kit qwrap example.tcl

                or
                 tclkit     sdx     qwrap example.tcl
        Windows: tclkitsh-win32.upx.exe sdx.kit qwrap example.tcl
        Now you have an example.kit Starkit (and, if you did this
        on a Windows host, an example.bat).  That's the Starkit.

Create a standard unwrapping:

Unix: tclkit sdx.kit unwrap example.kit

        Windows: tclkitsh-win32.upx.exe sdx.kit unwrap example.kit

Make a seperate copy of the tclkit executable for your target platform.

        You might want to call it something different, like ''tclkitcopy''
        to keep things straight.
        Keep in mind that Starpacks look "native"; they are platform-
        specific.  If you're working on Windows, and you're making a
        Starpack for Windows, just copy tclkit.exe into your local,
        working directory, at least for this demonstration.

Produce the starpack:

Unix: tclkit sdx.kit wrap example -runtime tclkitcopy

          Windows: tclkitsh-win32.upx.exe sdx.kit wrap example.exe -runtime tclkit-win32.upx.exe

Of course, on Unix-like systems, you will eventually learn that if you have your environment set properly, and sdx.kit permission modes set to execute, then you will be able to skip that initial word of the command and abbreviate things to:

Unix: sdx.kit wrap example -runtime tclkitcopy

or even

Unix: sdx wrap example -runtime tclkitcopy

Altogether, you can use the following script "tcl2exe":

#
# Creation of executables ("starpacks") that can run standalone starting from a TCL-script:
#
# Call: tcl2exe <tclscript> <platform>
#
# where the name of the TCL-script is given without extension, 
# and where <platform> is either linux or MinGW
#
# result: an executable named <tclscript>.exe
#
TCLScript=$1
Platform=$2
#
# Set the tools:
#
case $Platform in
#
  linux )
#
mytclkit=./tclkit-linux-x86
myruntime=$mytclkit
    ;;
#
  MinGW )
#
mytclkit=./tclkitsh-win32.upx.exe
myruntime=./tclkit-win32.upx.exe
    ;;
esac
#
# Construct executable:
#
$mytclkit sdx.kit qwrap $TCLScript.tcl
$mytclkit sdx.kit unwrap $TCLScript.kit
cp $myruntime tclkitcopy.exe
$mytclkit sdx.kit wrap $TCLScript.exe -runtime tclkitcopy.exe
#
# Clean up the dirt:
#
rm tclkitcopy.exe
rm $TCLScript.kit
rm -rf $TCLScript.vfs 
#

Just a note of clarification - if I am on, say, Windows, I can take a cross platform example.kit (assuming that in fact I created it as cross-platform), specify a tclkit for Solaris, or HP/UX, Linux, MacOS X, etc. and have as a result a starpack stand alone executable for that platform.

If, however, my starkit has platform specific components - compiled extensions, special platform-specific commands, etc. - then the starkit application is going to need to be updated to work on all the platforms for which I want to create starpacks.

JOB Assuming one might have created a subdirectory (registered in auto_path) say "dynlib" to hold all required platform specific dynamic loadable libraries, the following dispatcher code can be used to choose the OS dependent binary "on the fly":

# pkgIndex.tcl ---
# Tcl package index file.
# -------------------------------------------------------------------------
# Created by: Johann Oberdorfer
# This source file is distributed under the BSD license.
# -------------------------------------------------------------------------

# tree structure might look like
#  dynlib 
#  . AIX
#  .. sqlite3.6.10
#  .. tktable2.10
#  .. treectrl2.2.7
#  . Darwin
#  .. Tktable2.10
#  .. sqlite3.6.10
#  .. treectrl2.2.7
#  . Windows
#  .. Tktable2.10
#  .. sqlite3.6.10
#  .. treectrl2.2.8


# pay attention to the dir' structure and
# extend auto_path - if required, to make packages available

switch -glob -- $::tcl_platform(os) {
  "AIX"      { set libDir "AIX" }
  "Darwin"   { set libDir "Darwin" }
  "Windows*" { set libDir "Windows" }
  default    { set libDir "" }
}

if { $libDir == "" } {
  error "Libraries missing - please maintain lib directory!"
}

# re-assemble taking current dir into account:
set libDir [file join $dir $libDir]

               
if {[lsearch -exact $::auto_path $libDir] == -1} {
  lappend ::auto_path $libDir
}

This technique is not new, for sure, just thought, this info fits in here quite well...

How should your application look so that it makes a good starpack? "Starting effective starkit-based pure-Tcl development: the starkit::* namespace" addresses that question.