How to Use the Tcl Stubs Library

This page provides a "how to" guide to the stubs library found in the Tcl 8.1 and Tcl 8.2 releases. The main advantage of using the stubs library is that your extension can be linked once against the stubs library, and then be used with different versions of Tcl. Stubs were first introduced in Tcl 8.1, although you can also find an unreleased 8.0.6 version that supports stubs in the CVS repository. Another advantage of stubs is that you can create a statically linked Tcl shell and still be able to dynamically load a stubs-aware extension.

When you build or install Tcl, you will notice a new library, libtclstub8.1a. This library implements a dynamically bound interface to Tcl. In other words, it provides a level of indirection between the code in a Tcl extension and the Tcl library. The indirection is completed at runtime so your extension is not hardwired to a particular instance of the Tcl library. This is essentially the same thing that happens when you link against a shared library (e.g., a .dll, .so, or .sl file), except that Tcl implements the linking in a portable way.

In order to use the stubs library you need to make the following modifcations to your extension:

Add the -DUSE_TCL_STUBS and/or -DUSE_TK_STUBS flags to your makefile. You need to compile your code with these so that the Tcl API turns into macros that go through the stubs library.
Link against -ltclstub8.1 instead of -ltcl8.1
Include the following code as the first statement in your extension's Init procedure (e.g., Foo_Init)
```
    if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
	return TCL_ERROR;
    }
```
This call validates that the Tcl application that loads your extension can support the stubs interface you require (in this case, version 8.1 or later).

Add link to comments for /doc/howto/stubs.html

Last modified: April 24, 2001