Are there any newbie guides to the Tcl source?

This question has been raised repeatedly. The following page originated as an in early August 2008 from Neil Madden [1 ]: "It still changes quite a bit from release to release. Various bits are documented to some extent on the wiki ( ) -- search for 'Category Internals'.

The actual source code layout is fairly straightforward -- most C code is in generic/ with platform-specific stuff in win/ unix/ and macosx/. The library/ folder contains parts of the implementation that are Tcl scripts (e.g., parts of clock), and the init.tcl which is loaded into new interpreters. And so on.

The best place to start if you are new to the source is to get used to how Tcl extensions are written: how Tcl represents values (Tcl_Obj structure, and Tcl_ObjType), how commands are invoked (Tcl_ObjCmdProc), and so on. Several Tcl books cover this, and the wiki has plenty of information on this:

In the source, you can look at sample commands such as Tcl_IncrObjCmd in generic/tclCmdIL.c, or e.g. look at how lists are implemented in generic/tclListObj.c. Details of how [ open "|..."] is handled is platform-specific, so e.g. for unix systems this is unix/tclUnixPipe.c where TclpCreateProcess does a fork()/execvp() sequence.

If you want to get the heart of the interpreter, then look at generic/tclBasic.c, and in particular at the implementation of TclEvalObjvInternal (TEOVI as it is affectionately known). I'd advise grabbing a version of the source code from early 8.5 or even 8.4 branch, as TEOVI in HEAD (8.6) is rather more complex due to recent enhancements (indeed, it seems to have disappeared now, so look at Tcl_EvalObjv). After that, there is the byte-compiler in tclComp*.{h,c}, namespaces in tclNamesp.c, etc."

[Give advice to a simple scripter who's forced to go C-source-diving in order to figure out what a command really does in some tricky situation.]

DKF: Also, most of the readable command implementations are in generic/tclCmd*.c, especially before 8.6; the ones in other files can be rather complex at times. The individual command compilers (in generic/tclCompCmd*.c) aren't too bad in 8.6; they were much harder to read in 8.5 and before. (Mind you, you do need to know the bytecodes to be able to truly understand them, and some commands are a bit complex anyway.)