Cameron Laird's personal notes on how to use C with Tcl

[Events outside my control have caused several of the links to go bad recently. If there's one you particularly want, please let me know, and I'll update it. Otherwise, I expect to get around to this task in the summer of 2001.]

[I'm now keeping the most current information in the Wiki.]

This topic is easier than people expect. Dr. Ousterhout originally created Tcl as just such an extension language, and many have turned to it since then to meet exactly this need. However, in 1997 Tcl is often presented as a language in isolation, and beginners seem to have great difficulty figuring out how to smush together functionality coded in C and Tcl. Certainly "how do I use C with Tcl?" is one of the most frequently-asked questions in comp.lang.tcl, where it arises almost daily, to be answered with remarkable patience by the usual suspects (Jeffrey Hobbes, Larry Virden, ...). My own contribution is the pair of Regular Expression columns titled "..." and "...". Special thanks go to Katja Cremer for her help with the former of these.

"Building a custom tclsh" is the best place to start. This detailed article provides considerably more than the name suggests. In particular, it also steps a reader through the sequence necessary to generate an extended Wish, and informs beginners about "linking" concepts.

[re-organize. give prominence to JCW's tutorial]

A mid-December "Regular Expressions" column, "Scripted wrappers for legacy applications", introduces a short series of three columns on three architectures for putting together C and Tcl code (and related topics).

[Explain it might not be necessary. Point to exec tutorial.]

Helmut Giese's site "contains some fine coding examples of integrating Tcl with C and C++."

Brent Welch's chapter on "C Programming and Tcl" from the third edition of his book emphasizes extensions to the Tcl (Tk) shell, but it has most of what a programmer looking to embed Tcl needs. It includes a great deal of valuable information on the object format, the event loop, and encodings.

Different modes

One confusion Tcl elicits in some beginners is about the multiplicity of architectural models Tcl supports. It's important to understand that there are several different ways to "glue" together components scripted in Tcl with objects coded in C or other compiled languages. Don Porter outlines the possibilities in a response to a Usenet question.

C programs can invoke Tcl scripts

The C API, for example, assumes that the Tcl and C libraries are bound together in a single application, to be executed as a single process. Suppose, for instance, a minimal C program, such as
	int main(argc, argv)

	int argc;
	char **argv;
	{
		char *my_string;

		my_string = "MagicWord";
		printf("The secret is '%s'.\n", my_string);
	}
     
If you want my_string to be visible from within a Tcl script, you might augment this source to read
	#include <tcl.h>
	int main(argc, argv)

	int argc;
	char **argv;
	{
		char *my_string;
		Tcl_Interp *interp;

		my_string = "MagicWord";
		printf("The secret is '%s'.\n", my_string);
		interp = Tcl_CreateInterp();
		(void) Tcl_SetVar(interp, "my_string", my_string, 0);
		(void) Tcl_EvalFile(interp, "/tmp/myscript.tcl");
	}
     
and supplement it with a new file, /tmp/myscript.tcl:
	puts "Within this Tcl script, my_string has the value '$my_string'."
     
Although the script is a distinct file, in this model it's evaluated within the same process as the (modified) C program.

WARNING: with Tcl8.0 and after, it's important to do a Tcl_FindExecutable(argv[0]) before Tcl_Init(), even though this isn't clearly documented.

J. Adrian Zimmer proposes that those looking for more on this topic read his book:

Ousterhout's book has about 80 pages devoted to the Tcl API. My recent book has 100 pages. However, although I cover Tk, I do not cover the Tk API so my total page count for the C API is less than Ousterhout's.

I don't try to cover everything about the API for Tcl but I do give complete examples that compile with Unix (BSDI) or Windows (Borland). Also, I do discuss the Tcl_Obj data type and how programming for it differs from earlier APIs.

[Explain Scriptics documentation on this subject.]

Extending Tcl with C codings

JCW has written a thoughtful tutorial, "How to use extensions in Tcl".

Frank Pilhofer explains the chore of making loadable C++ extensions; note, though, that advances in gcc 2.8 and egcs superannuate some of this information.

Uwe Guehl has a nice, small, complete example using 8.0+ objectification.

...

[Organize and annotate the following]

tutorials

[Explain mktclapp]

Eric's example

SWIG and jWrap

[Ousterhout book remains the standard for explaining how to extend by writing in C.]

[Explain which books are most accessible--Ousterhout, Johnson, ...]

[Coming up, late 1997: long commentary on ET.]

[Much more to come.]

[Write PC time-of-event example]

jWrap [explain]

[Does the tkHelloWorld example no longer link properly?]


Cameron Laird's personal notes on how to use C with Tcl/claird@phaseit.net