[Starkit]s and their interaction with binary [extension]s 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.
 
See also [sdx].

----
I am uncertain why [tclkit]s are not built with [thread]ing enabled; perhaps
it is a performance concern?  Or perhaps something included in the tclkit
is not yet thread safe?

----
[AM] I solved a problem that arose with a script that uses Itcl/Itk/Iwidgets - see [Starkit with Iwidgets] 
----
See also [Creation of multi-platform Starkitted binary packages]
----
[Category Deployment] | [Category Tclkit]