Building Tcl 8.6 single file applications - a step-by-step guide

Published 2020-12-28

There is plenty of reference material on the Internet about building single file applications with Tcl but as is often is the case, some bit rot has set in that makes it confusing for new users. Taking a break from our series on Tcl 8.7, this short post aims to remedy that by providing a step-by-step guide for the process.

Note however that there are a lot of base technologies (tclkits, freewrap etc.), each of which additionally have multiple levels of functionality with a variety of configuration options. This post provides a recipe for building a single file application for just one specific combination based on the tclkit core. It does not go into any level of detail; for that, see one of the references listed at the end.

The sample application we will create, demo.exe, prints all numbers supplied as arguments on the command line using a package we call adder.

Step 1: download prerequisites

To build a Tcl application as a single file executable, you need a single file Tcl shell (that includes Tk if you are building a GUI application) and the sdx tool for combining your own library and application components (including scripts and binaries) into a single file executable.

Download a single file Tcl shell based on tclkit technology from rkeene.org. The sample session below uses the console version (without Tk) targeting 64-bit Windows. If a suitable version for your platform is not available there, or if you need additional common extensions, you can build and download a custom version.

Download the sdx tool from any one of the many sites hosting it such as this one.

For convenience, the session below assumes both are renamed.

D:\Temp\blog>move sdx-20110317.kit sdx.kit
        1 file(s) moved.
D:\Temp\blog>move tclkit-cli-8_6_10-twapi-4_4_1-x64-max.exe tclkit.exe
        1 file(s) moved.

Step 2: create the directory layout

Our directory layout will be based on the default directory layout expected by the sdx and tclkit based tools. Create the following directory structure:

D:\Temp\blog>mkdir demo.vfs
D:\Temp\blog>mkdir demo.vfs\lib

The top-level directory should be named after the application demo and have an extension of .vfs. This is only because we are conforming to expected defaults.

Step 3: copy any required packages

Add any required packages under the lib subdirectory. In our application, only the adder package is required. Create the demo.vfs/lib/adder directory.

D:\Temp\blog>mkdir demo.vfs\lib\adder

Add the package's files to this directory.

# File: demo.vfs/lib/adder/adder.tcl
proc add args {
  return [tcl::mathop::+ {*}$args]
}

package provide adder 1.0

The corresponding package index:

# File: demo.vfs/lib/adder/pkgIndex.tcl
package ifneeded adder 1.0 [list source [file join $dir adder.tcl]]

Step 4: add your application files

Create a directory to contain your application files. There is no specific requirement here about where you place your files within the directory structure. For our simple application, create a directory for the application files.

D:\Temp\blog>mkdir demo.vfs\app

Add a demo.tcl file to it.

# File: demo.vfs/app/demo.tcl
package require adder
puts "The sum is [tcl::mathop::+ {*}$::argv]"

Step 5: create the main script

The startup script must be called main.tcl and placed at the top level of the directory structure.

# File: demo.vfs/main.tcl
package require starkit
starkit::startup
source [file join [file dirname [info script]] app demo.tcl]

The main.tcl script may be a stub that loads the real application, as above, or it could be the entire application, or anything in between. However, the first two commands are mandatory. The first command loads the core functionality required to support tclkit/starkit that is built into the tclkit executables. The next command starkit::startup does some required initialization such as setting up the Tcl auto_path to look for packages in the lib subdirectory.

Step 6: build the executable

Finally, build the application executable using the sdx tool. This combines a Tcl single file executable, the runtime, with the application directory tree into a single executable. Because of some sdx and platform limitations, this runtime file must be a different physical file than the executable used to run the sdx tool. So first, we need to make a copy of the tclkit we downloaded.

D:\Temp\blog>copy tclkit.exe runtime.exe
        1 file(s) copied.

Now run the sdx wrap command to create our final executable.

D:\Temp\blog>tclkit sdx.kit wrap demo -runtime runtime.exe
886 updates applied
6 updates applied

Note that the runtime need not be a copy of the tclkit executable used to invoke sdx. For example, it may be a tclkit version that includes Tk if the application is GUI-based.

A quirk of the sdx tool is that it does not give the output file a file type on Windows so we need to rename it before running. This step is not needed on other platforms.

D:\Temp\blog>rename demo demo.exe

The created executable can now be run on any system by just copying it. It does not need to have a Tcl interpreter pre-installed or any other supporting files.

D:\Temp\blog>demo 1 2 3
The sum is 6

Conclusion

As stated earlier, the recipe above is just one way to construct a single file Tcl application. Several other alternatives exist (freewrap et al) and even with the tclkit/sdx tools, many other configurations are possible, either simpler or more generalized. The sdx tool also provides many facilities for examining and manipulating tclkits. See the references for more detail.