Starkits with Binary Extensions

Starkits and their interaction with binary extensions are a bit of magic, but the simpler cases are quite easy to do and understand.

Simple case: Single platform, stubs enabled binary extensions with no external dependencies.

This is the easy case for packages like tdom or tktable, which do not depend on external .so or .dlls to work. Put the .so/.dll in the virtual filesystem and write/use a pkgIndex.tcl file that loads it when a package require is done. For many packages, copying the package subdir of /lib into the $::starkit::topdir/lib dir of the vfs is enough to make it work. (Windows users should note that DLL names in pkgIndex.tcl are case sensitive once wrapped into a .kit file, so a load which works when running against a .vfs directory may not work with a wrapped binary. - Twylite)

Example:

 # binary.tcl
 package require Tk
 package require Tktable
 puts "Loaded ok"

Wrap it and unwrap to create directory:

 sdx.kit qwrap binary.tcl
 sdx.kit unwrap binary.kit

Copy the binary Tktable libs in:

 cp /path/to/Tktable2.8 binary.vfs/lib

Rewrap the code:

 sdx.kit wrap binary

Medium case: Multiple platform, stubs enabled binary extension with no external dependencies.

Toby Is it sufficient to do as above, but copying the right (tm) binary?

Harder case: Single platform, stubs enabled binary extension with external dependencies.

(The assumption for this section is that I'm using Windows)

The problem is that a particular DLL to be loaded is dependent on another non-system DLL. This DLL is stored alongside the DLL to be loaded. An example of this is the requirement for inpout32.dll in lpttcl. Of course the easiest solution would be to move the dependent DLL to the SYSTEM32 directory so the DLL reference can be resolved in the usual way. But if filling the SYSTEM32 with a bunch of random DLLs is not desired, there is a work around.

The solution is to explicitly load the dependent DLL using a windows kernel call, LoadLibrary. To access this call, I use the Ffidl package (you could use TWAPI as well).

load [file join [file dirname [info script]] ffidl06.dll]
::ffidl::callout _LoadLibrary {pointer-utf8} int [::ffidl::symbol kernel32 LoadLibraryA]

# define a procedure to load the library. This procedure must copy the DLL to
# a temporary location because if it is called from a starkit, it won't physically
# present
proc LoadLibrary fname {
    set dllname [file tail $fname]
    set tmpfile [file join $::env(TEMP) $dllname]
    if {![file exists $tmpfile]} {
        file copy -force $fname $tmpfile
    }
    return [_LoadLibrary $tmpfile]
}

So now, to load a package, you use LoadLibrary to load all dependent DLLs before using the load command. For example, to load lpttcl, I do the following...

LoadLibrary [file join [file dirname [info script]] inpout32.dll]
load [file join [file dirname [info script]] lpttcl.dll]

Impossible case: Non stubs enabled, shared library binary extension.

Zarutian 31. july 2004: How portable are those extensions?

Depends. Many are just ANSI C, others are complex and interact with the platform.

LV What does portable mean to you? A binary extension, by its very nature, means that code using it will only run on platforms compatible with the binary portion of the code. So, if you want the code to run on 10 hardware/operating system platforms, you need to build the binaries for each of those combinations and make certain that the package loads appropriately.

snichols I noticed that starkits do not work with the binary Thread Tcl extension or support threaded Tcl scripts. I sort of got this working by putting all my Tcl code in main.tcl and putting the Lib folder outside the starkit. It's almost like a normal Threaded Tcl interpreter at this point. I'd prefer that starkits support Tcl threads with multiple source Tcl scripts and the lib folder could be included in the kit file.