!!!!!! '''[Tcl Tutorial Index]''' !!!!!! <> **General information on Tcl and C** Tcl can be regarded as a powerful configuration language sitting on top of a bunch of [C] functions. Tcl's original purpose (according to Tcl's inventor John Ousterhout (see [How do I use the Tcl C API?])), was to create a standard language that could be embedded in applications. The intent was that Tcl would be accessed only via its C API. Today, the typical use is via the [tclsh] or [wish] interpreters at the scripting level. If you want to learn more about the C core of Tcl and how it is working, start here: [The Tcl Core]. **Extending Tcl** This C API can be use to extend Tcl, giving it new commands and new functionality (see [Extending Tcl]). The recommended way for this is to use Tcl's Extension Architecture [TEA], a set of guidelines and techniques for the distribution, configuration, compilation, and installation of Tcl extensions. TEA comes with a "sample extension" showing how to do things: * [SampleExtension] Regardless whether you are writing an extension in C or Tcl, here is some more information: * [How to build good packages] * [Tips for writing quality software] * [How to Write Quality Documentation] * [C-like include in tcl] * [Solutions for Extension Building] * [Tcl extension prototype - proto.cpp] (in C++) * [Invoking Tcl commands from Cplusplus] * [Useful C Commands For Tcl] * [HOWTO: Make a Tcl Extension Thread-Safe] (examples of thread-safe extensions: [Thread-safe Tcl Extensions] * [Extending Tcl] (most info on that page is also included here) ***Hello world*** To see how extendind Tcl works in practice, you should have a look at the typical 'Hello world' example: * [Hello World as a C extension] * [Building the Hello C Extension using Visual Studio 2010 express] There are also other examples of small extensions in C: * [RPN C extension for Tcl] * [rphoto] (fast photo image rotation) One thing you might wonder about is the return value of a C function implementing a Tcl command. In Tcl, a [proc]edure will always [return] the value that you want to use outside the procedure, in the code calling the procedure. In C, a function implementing a Tcl command must return a status code that is typically either Tcl_OK or TCL_ERROR (there are also TCL_BREAK, TCL_CONTINUE and TCL_RETURN for special cases). The Tcl value which is returned on the script level is stored in the Tcl_Obj that was passed as an argument to the C function implementing the Tcl command. This is done using functions such as [Tcl_SetResult]/[Tcl_SetObjResult], [Tcl_AppendResult], [Tcl_AppendElement] together with [Tcl_GetObjResult] and [Tcl_GetStringResult]. ***More on TEA*** The Tcl Extension Architecture is a whole story in itself. TEA is largely defined by the tcl.m4 file in [tclconfig], along with the `configure.in` and `Makefile` files in the sample extension. A `makefile.vc` and `rules.vc` file is also included for Windows builds. TEA describes a directory layout both for the source distribution and for files installed as part of the extension. Files in the source distribution of an extension are laid out such that platform-specific components live in a directory dedicated to that platform. The version of TEA is defined by the TEA_VERSION variable in the tcl.m4 file in [tclconfig]. Here are some pages dealing with TEA: * [TEA] * [TEA2] * [TEA3] * [Converting your Tcl extension to TEA2] * [TEA: a summary of trying to use it, Vince Darley] * [Annotated 10 steps to success with TEA] Examples of existing extensions using TEA are: [Tktable], [TclX], [itcl/itk]. ***Extending Tcl (with C) from within Tcl*** Going one step further, you can even extend Tcl with a C function that is written inside the Tcl script where you need it: * [Critcl] * [Critcl builds C extensions on-the-fly] * [tcltcc] * [Extending Tcl in C from Tcl] **Embedding Tcl** Of course, you can also still use Tcl as embedded language in you application. Here are some pages about this, including customization of [tclsh] itself: * [How to embed Tcl in C applications] * [Combining Fortran and Tcl in one program] * [Building a custom tclsh] * [Experiences with a custom tclsh] Embedding Tcl typically involves using the C API function [Tcl_Init]. **The Tcl C API** All the Tcl C API functions have manual pages (see https://www.tcl.tk/man/tcl/TclLib/contents.html%|%here%|%). However, the Wiki has also a bit of information on some of the API functions. Start with the list of function here: * [Tcl C API] There are some common design principles in the C API which you can read about here: [Tcl C API Design Principles]. Some special information on certain aspects of the Tcl C API can be found here: * [Using Tcl_ListObj and his friends] * [Tcl Handles] * [DString] (easy handling of dynamically growing strings!) * [Tcl_GetStringResult() forward compatibility] (direct use of interp->result is now forbidden) ***About the string interface and the Tcl_Obj interface*** Prior to Tcl version 8, the C interface for Tcl commands was string oriented (fitting Tcl's philosophy of [everything is a string]. As this resulted in a lot of conversions when you wanted integers, doubles, lists from this string, Tcl 8 introduced a new interface based on the [Tcl_Obj] C type. This type can store the various incarnations of a Tcl value at the same time, doing the necessary conversions between types in a lazy fashion. This helped to speed up Tcl and made scripts run more efficiently. Note: Although Tcl_Obj is termed an "object", it has nothing to do with object-oriented programming (that's what [TclOO] is for). Think of Tcl_Obj as a Tcl value with different clothes on. Depending on your needs, Tcl will provide you with the Tcl value dressed differently. Some of the Tcl_Obj functions come in two flavours, e.g. [Tcl_GetString] and [Tcl_GetStringFromObj]. Don't get confused, both are dealing with Tcl_Obj and return the string representation of a Tcl_Obj although it looks like the first is dealing with strings only and the other with Tcl_Obj! The difference is just that you may sometimes be interested in not only getting the string itself but also the length of the string. If so, you can use [Tcl_GetStringFromObj] instead of [Tcl_GetString]. **The Tk C API** Just as Tcl, also Tk has its own C API. Here is a list (probably incomplete) with more information on at least a few of the Tk C functions: * [Tk C API] Here is some more information (and examples) on extending Tk: * [Adding Tk to an existing Xt program] ---- <> Tcl Library | Tk Library | Tutorial !!!!!! '''[Tcl Tutorial Index]''' !!!!!!