Version 44 of Build Your First Starkit

Updated 2009-11-09 03:39:16 by SEH

Purpose: to guide a new user through the steps of building a starkit.

Starkits rely on a feature of Tcl/Tk 8.4 called the Virtual File System (VFS). Through the magic of VFS, a starkit contains an entire directory structure, including scripts, libraries, and even data files. The trick is to set up a structure which works in unpacked form while coding and testing, and which can later be assembled into an equivalent packaged starkit. Fortunately, all the infrastructure and tools are provided for you, and the whole process is very easy.

STEP 1: Get Tclkit and sdx Note: the tclkit web site is now at Google Code [L1 ]: check there first for tclkit and sdx.

The Unix, Linux and Mac binaries need to be unpacked, renamed, and made runnable:

    gzip -d tclkit-*.gz
    mv tclkit-* tclkit
    chmod +x tclkit

On UNIX/Linux/MacOS X, be certain that tclkit is in a directory that is in your $PATH.

SDX is the Starkit Developer eXtension. It is a starkit containing tools for manipulating Starkits and Starpacks. Get sdx.kit from . Since it's a starkit, you run it with the command

    tclkit sdx.kit

If this command responds with the error "can't find package starkit" then you need to add read permissions to your tclkit binary. On UNIX/Linux type systems, this would be via:

    chmod u+r tclkit


LV 2007 July 05

Question: Should I expect to get equivalent results if I replace a tclkit with an ActiveTcl base-tk file?

STEP 2: Wrap Your Application

You can easily wrap any single file Tcl application. For this example, create a file named "hello.tcl" and use the following two lines of text as its contents:

        package require Tk
        pack [button .b -text "Hello World!" -command bell]

Use sdx's "qwrap" option to quickly turn a single script into a starkit:

        tclkit sdx.kit qwrap hello.tcl

The result is a file called hello.kit. On Windows, SDX will also create a file hello.bat. Type "hello" on Windows, or "./hello.kit" on Unix. You'll see a window with button which beeps when clicked

STEP 3: Unwrap Your Application

Your wrapped application contains an entire virtual file system. In this case, we have just one script file, but even this simple application has all the virtual file system support you would get with a complex applcation. To see the contents of your starkit, unwrap it like this.

        tclkit sdx.kit unwrap hello.kit

This creates a copy of hello.kit's virtual file system in a directory named "hello.vfs/". You will find the startup script at "hello.vfs/main.tcl", and your hello.tcl script has been converted into a package in hello.vfs/lib/app-hello/.

STEP 4: Make Changes

One of the benefits of starkit applications is that they run exactly the same way wrapped or unwrapped. Both these commands will execute your application, and your application will execute identically.

    tclkit hello.kit
    tclkit hello.vfs/main.tcl

So you can continue application development in the unwrapped starkit. Add scripts, data files, or packages under hello.vfs/lib/, and they will all be found by your application. Work on the unwrapped application until it's just right.

AT[L2 ] I would mention here that running it as a starkit is different than running it as a starpack because the path is different...this caused me confusion the first time I built a star(pack|kit). LV AT, what do you mean when you say because the path is different?

STEP 5: Wrap It Up

When you are ready to create an updated starkit, do:

        tclkit sdx.kit wrap hello.kit

This takes hello.vfs/ as input, and overwrites hello.kit as before, creating an application that can be run with "hello" (Windows) or "./hello.kit" (Unix)

Notice that your application development structure (hello.vfs/) is exactly the same as the starkit. And your starkit will run on any plaform with a Tclkit binary runtime because in this case, the application makes use of only scripts in the starkit and packages in tclkit.

2005-7-21 JM When trying the last step (update the kit), I am getting the following error: "Couldnt open Hello.kit", the file is not set to "read only" and it exists. I also tried the -writable (it also appears as -writeable in some places in this wiki) and the error still showing up. (I am using Windows XP)

LV I don't have a Windows system handy. Did you try typing the name as lower case? It may not make a difference, but I notice the example shows a lower case "hello"...

RLH - If I remember I will post the contents of a make.bat file that I use to automate the process for me.

JM I tried all these instructions again in a different machine (same OS: WXP) and I am geting same error at step 5, being a little bit more verbose here, some more information about the error message is:

 "couldn't open "hello.kit": invalid argument while executing "open $name w"
 (procedure "writefile" line 2)..."

I typed all the letters lower case. I did it again just to double check. same error...

Have you tried copying tclkit.exe sdx.kit and hello.kit into the same folder? Sounds like it MIGHT be looking in the wrong folder for hello.kit?

PT - 22-Jul-2005: Under windows you should use tclkitsh to drive sdx.(which you can get from ) tclkit.exe will create a toplevel and with the current version it seems to leave the process alive by hidden. The likely issue above is that the hello.kit file is already opened for writing by a previous instance that you will have to kill. The following batch file should help. Call it sdx.bat and put it in a folder listed in your PATH environment variable:

 @echo off
 tclkitsh c:\Path\To\sdx.kit %1 %2 %3 %4 %5 %6 %7 %8 %9

Then you can just issue sdx wrap hello.kit like the unix users.

JM It is working now. Thanks.

ET: tclkit sdx.kit opens a console window on Windows for output. If you just close this, there's still a tclkit running, only it has no window, so you'd have to kill it by process id. To clean up, type "exit" (or choose exit in the file menu) in the console window, and you won't leave a tclkit running that's hard to kill off.

Getting tclkitsh

There are two sections in .

For some reason, The titles of such sections appear just as a black bar in my FireFox browser. So the second section contains the "Tclkitsh (cmdline, no Tk)"

RLH 2005-07-22: For Windows 2000/XP I create these simple bat files to help me create a starkit. It is a given that I am not a very good bat creator. : )

 @echo off
 echo "Wrapping and Unwrapping popups..."
 tclsh.exe c:\Tcl\bin\sdx.kit qwrap popups.tcl
 tclsh.exe c:\Tcl\bin\sdx.kit unwrap popups.kit
 echo "Copying mime into the archive"
 xcopy C:\Tcl\lib\tcllib1.7\mime "C:\Path_to_vfs\Popups.vfs\lib\mime\" /s /v /y
 echo "Copying MD5 into the archive"
 xcopy C:\Tcl\lib\tcllib1.7\md5 "C:\Path_to_vfs\Popups.vfs\lib\MD5\" /s /v /y
 echo "Copying base64 into the archive"
 xcopy C:\Tcl\lib\tcllib1.7\base64 "C:\Path_to_vfs\Popups.vfs\lib\base64\" /s /v /y
 echo "Creating the EXE file"
 tclsh.exe c:\Tcl\bin\sdx.kit wrap popups.exe -runtime c:\Tcl\bin\tclkitsh.exe
 echo "Deleting unnecessary files..."
 del popups.bat /q
 del popups.kit /q
 rmdir popups.vfs /s /q
 echo "Popups executable built..."

MHo: Take a look at Windows batch script for 'compiling' starpacks.

RPH: Is it possible to cross-build a StarKit? If so how is it done?

MSH: By default a starkit is cross-platform as it needs a local tclkit executable to run on a platform, except binary extensions which must be stubs aware and have each .dll/.so for the required platforms and a pkgindex which loads the correct extension.