Updated 2012-02-09 17:40:15 by GJW ▲

There are several pages on this Wiki with hints for writing C and C++ extensions.

At best, the Tcl Extension Architecture must be considered to be in somewhat a state of flux. Vince Darley's screed, Annotated 10 steps to success with TEA, makes interesting reading, and reveals some frequently made mistakes in trying to build extensions for the first time on Windows. Certainly, we all want to find an easier way to get started!

Pages on this Wiki of interest to extension developers

  • Hello World as a C extension provides a bare-bones sample extension in C with details of how to actually set up your environment and build an actual extension, and then how to load it into Tcl to try it out.
  • Tcl Handles - Presents in detail two methods for representing pointers to the Tcl program. The first represents program objects with Tcl command names; the second uses opaque "handles". These are the two fundamental ways to pass around C/C++ structures in Tcl scripts.
  • Invoking Tcl commands from Cplusplus - A C++ class that allows fast callbacks from C++ to tcl commands.
  • Cplusplus streams and Tcl channels - A C++ iostream class that connects to a Tcl I/O channel. Includes initialization code to remap cin, cout and cerr to the Tcl channels stdin, stdout, and stderr so that C++ I/O happens on the Tcl console.
  • Managing the reference count of Tcl objects - A summary of when to use Tcl_IncrRefCount and Tcl_DuplicateObj
  • Blessed Tcl_Obj values
  • RS's three-part 'Xmas2000' project presents some Tcl scripts, the C Code Generators, that generate - automatically - the repetitive C code that extensions use to get themselves connected with the Tcl interpreter. He didn't manage to build a loadable DLL on his slightly ancient gcc though...
  • Taking things one step beyond Richard's scripts, the SWIG system [1] is a software development tool that connects programs written in C, C++, and Objective-C with a variety of high-level programming languages. SWIG is primarily used with common scripting languages such as Perl, Python, Tcl/Tk, Ruby, and Guile but has also been extended to include languages such as Java and Eiffel.
  • Moving one step further still, if your only purpose for developing an extension is to provide an interface to some third-party library, you may be able to avoid writing any C or C++ code altogether. The Ffidl extension [2] provides a nearly universal means of invoking shared libraries from Tcl on a number of platforms.
  • How to build good packages

Also of interest may be the Tcl Engineering Manual [3] and the "Tcl Extension Architecture" manual [4].

Tutorial for the extension user:

JCW has written a tutorial on how to use a Tcl extension at [5]. This paper is a fine "how-to" for those who find themselves needing to build extensions that other people have written.

Tutorial for the extension writer:

In addition to the TEA documentation at [6], extension writers will likely want to examine:

  • Brent Welch. "C Programming and Tcl" and "Compiling Tcl and Extensions." Practical Programming in Tcl and Tk, 3rd ed. (Prentice Hall, 1999) pp. 603-651. These chapters are available on the Web at [7] and [8].

Slightly obsolete tutorials on extension writing:

Cedric Beust [mailto:beust@modja.inria.fr] has written a short article giving guidelines on where to start when writing a Tcl extension. You may find it at [9]. It is titled "Writing a Tcl extension: the Toocl example" and describes the work done on the Tooltalk extension. The paper is dated August 10, 1993, and hence predates the Tcl_Obj API's.

An HTML version of the TclCommandWriting man page that comes with TclX has been made available on the WWW at [10] . This page explains the C API to Tcl, providing an introduction/tutorial on writing Tcl extensions. This paper, too, predates the Tcl_Obj API's.

IDG An attempt to access this produces: Forbidden You don't have permission to access /~joem/CmdWrite.html on this server.

With both of the last two papers, it is important to note that direct use of interp->result is now forbidden. An extension that scribbles on interp->result will get pointer smashes. All uses of interp->result have to be replaced with appropriate uses of Tcl_GetStringResult and Tcl_SetResult or their Tcl_Obj counterparts.

Unix specific pages:

Frank Pilhofer [mailto:fp@fpx.de] has a web page at [11] which points to a document on building Tcl extensions from C++ code. This document gives an overview of the various platform-dependent tricks needed to make C++ extensions work in the various Unix environments.

A different Frank, Frank Stajano, presented a paper at the 1998 Python conference with insights into why he thinks Python's extensions are evolving faster and are easier to work with than Tcl's [12]. The relevant comments are in section 3 of the paper.

Windows-specific pages

For information at building Tcl extension using Cygnus's Cygwin environment, take a look at the following files:

Another way to get an extension off the ground in no time is Critcl, described in [17] -jcw

Simplest possible start 1: contents of the unix/dltest directory of the source distribution.

Simplest possible start 2, contributed by Ralf Fassel, stubs support added by George Peter Staplin:
    /* hello.c */
    #include <stdio.h>
    #include <stdlib.h>
    #include <tcl.h>
    int
    hello(/* args ignored */)
    {
      printf("hello world");
      return TCL_OK;
    }
    int
    Hello_Init(Tcl_Interp *interp)
    {
      if (NULL == Tcl_InitStubs (interp, TCL_VERSION, 0))
        return TCL_ERROR;

      printf("this is hello loading");

      Tcl_CreateCommand(interp, "hello", hello, NULL, NULL);
      return Tcl_PkgProvide(interp, "Hello", "1.0");
    }
    /* End of file */

    % gcc -shared -o /tmp/hello.so hello.c
    % tclsh
    % load /tmp/hello.so

For stubs:
    $ gcc -shared -o hello.so -DUSE_TCL_STUBS hello.c /path/to/libtclstub84.a -lm -Wl,-rpath=/path/to/dir/with/libtcl84.so
    $ tclsh8.4
    % load ./hello.so

Not-quite-simplest-but-somehow-still-appealing start 3, observed by LV: ftp://ftp.tcl.tk/pub/tcl//nightly-cvs/sample-20031018.tar.gz

See also:

Category PortingCategory Package