Tcl by John Ousterhout University of California at Berkeley ouster@cs.berkeley.edu 1. Introduction --------------- This directory contains the sources and documentation for Tcl, an embeddable tool command language. The information here corresponds to release 7.3. 2. Documentation ---------------- The best way to get started with Tcl is to read the draft of my upcoming book on Tcl and Tk, which can be retrieved using anonymous FTP from the directory "ucb/tcl" on ftp.cs.berkeley.edu. Part I of the book provides an introduction to writing Tcl scripts and Part III describes how to write C code that uses the Tcl C library procedures. The "doc" subdirectory in this release contains a complete set of manual entries for Tcl. Files with extension ".1" are for programs (for example, tclsh.1); files with extension ".3" are for C library procedures; and files with extension ".n" describe Tcl commands. The file "doc/Tcl.n" gives a quick summary of the Tcl language syntax. To print any of the man pages, cd to the "doc" directory and invoke your favorite variant of troff using the normal -man macros, for example ditroff -man Tcl.n to print Tcl.n. If Tcl has been installed correctly and your "man" program supports it, you should be able to access the Tcl manual entries using the normal "man" mechanisms, such as man Tcl 3. Compiling and installing Tcl ------------------------------- This release should compile and run "out of the box" on any UNIX-like system that approximates POSIX, BSD, or System V. I know that it runs on workstations from Sun, DEC, H-P, IBM, and Silicon Graphics, and on PC's running SCO UNIX and Xenix. To compile Tcl, do the following: (a) Type "./configure" in this directory. This runs a configuration script created by GNU autoconf, which configures Tcl for your system and creates a Makefile. The configure script allows you to customize the Tcl configuration for your site; for details on how you can do this, see the file "configure.info". (b) Type "make". This will create a library archive called "libtcl.a" and an interpreter application called "tclsh" that allows you to type Tcl commands interactively or execute script files. (c) If the make fails then you'll have to personalize the Makefile for your site or possibly modify the distribution in other ways. First check the file "porting.notes" to see if there are hints for compiling on your system. If you need to modify Makefile, there are comments at the beginning of it that describe the things you might want to change and how to change them. (d) Type "make install" to install Tcl binaries and script files in standard places. You'll need write permission on /usr/local to do this. See the Makefile for details on where things get installed. (e) At this point you can play with Tcl by invoking the "tclsh" program and typing Tcl commands. However, if you haven't installed Tcl then you'll first need to set your TCL_LIBRARY variable to hold the full path name of the "library" subdirectory. If you have trouble compiling Tcl, I'd suggest looking at the file "porting.notes". It contains information that people have sent me about changes they had to make to compile Tcl in various environments. I make no guarantees that this information is accurate, complete, or up-to-date, but you may find it useful. If you get Tcl running on a new configuration, I'd be happy to receive new information to add to "porting.notes". I'm also interested in hearing how to change the configuration setup so that Tcl compiles on additional platforms "out of the box". 4. Test suite ------------- There is a relatively complete test suite for all of the Tcl core in the subdirectory "tests". To use it just type "make test" in this directory. You should then see a printout of the test files processed. If any errors occur, you'll see a much more substantial printout for each error. See the README file in the "tests" directory for more information on the test suite. 5. Summary of changes in recent releases ---------------------------------------- Tcl 7.3 is a minor release that includes only one change relative to Tcl 7.1 (it fixes a portability problem that prevented tclMain.c from compiling on some machines due to a missing R_OK definition). Tcl 7.3 should be completely compatible with Tcl 7.1 and Tcl 7.0. Tcl 7.2 was a mistake; it was withdrawn shortly after it was released. Tcl 7.1 is a minor release that consists almost entirely of bug fixes. The only feature change is to allow no arguments in invocations of "list" and "concat". 7.1 should be completely compatible with 7.0. Tcl 7.0 is a major new release that includes several new features and a few incompatible changes. For a complete list of all changes to Tcl in chronological order, see the file "changes". Those changes likely to cause compatibility problems with existing C code or Tcl scripts are specially marked. The most important changes are summarized below. Tcl configuration and installation has improved in several ways: 1. GNU autoconf is now used for configuring Tcl prior to compilation. 2. The "tclTest" program no longer exists. It has been replaced by "tclsh", which is a true shell-like program based around Tcl (tclTest didn't really work very well as a shell). There's a new program "tcltest" which is the same as "tclsh" except that it includes a few extra Tcl commands for testing purposes. 3. A new procedure Tcl_AppInit has been added to separate all of the application-specific initialization from the Tcl main program. This should make it easier to build new Tcl applications that include extra packages. 4. There are now separate manual entries for each of the built-in commands. The manual entry "Tcl.n", which used to describe all of the built-ins plus many other things, now contains a terse but complete description of the Tcl language syntax. Here is a list of all incompatibilities that affect Tcl scripts: 1. There have been several changes to backslash processing: - Unknown backslash sequences such as "\*" are now replaced with the following character (such as "*"); Tcl used to treat the backslash as an ordinary character in these cases, so both the backslash and the following character would be passed through. - Backslash-newline now eats up any white space after the newline, replacing the whole sequence with a single space character. Tcl used to just remove the backslash and newline. - The obsolete sequences \Cx, \Mx, \CMx, and \e no longer get special treatment. - The "format" command no longer does backslash processing on its input string. You can invoke the shell command below to locate backslash uses that may potentially behave differently under Tcl 7.0. This command will print all of the lines from the script files "*.tcl" that may not work correctly under Tcl 7.0: egrep '(\\$)|(\\[^][bfnrtv\0-9{}$ ;"])' *.tcl In some cases the command may print lines that are actually OK. 2. The "glob" command now returns only the names of files that actually exist, and it only returns names ending in "/" for directories. 3. When Tcl prints floating-point numbers (e.g. in the "expr" command) it ensures that the numbers contain a "." or "e" so that they don't look like integers. 4. The "regsub" command now overwrites its result variable in all cases. If there is no match, then the source string is copied to the result. 5. The "exec", "glob", "regexp", and "regsub" commands now include a "--" switch; if the first non-switch argument starts with a "-" then there must be a "--" switch or the non-switch argument will be treated as a switch. 6. The keyword "UNIX" in the variable "errorCode" has been changed to "POSIX". 7. The "format" and "scan" commands no longer support capitalized conversion specifiers such as "%D" that aren't supported by ANSI sprintf and sscanf. Here is a list of all of the incompatibilities that affect C code that uses the Tcl library procedures. If you use an ANSI C compiler then any potential problems will be detected when you compile your code: if your code compiles cleanly then you don't need to worry about anything. 1. Tcl_TildeString now takes a dynamic string as an argument, which is used to hold the result. 2. tclHash.h has been eliminated; its contents are now in tcl.h. 3. The Tcl_History command has been eliminated: the "history" command is now automatically part of the interpreter. 4. The Tcl_Fork and Tcl_WaitPids procedures have been deleted (just use fork and waitpid instead). 5. The "flags" and "termPtr" arguments to Tcl_Eval have been eliminated, as has the "noSep" argument to Tcl_AppendElement and the TCL_NO_SPACE flag for Tcl_SetVar and Tcl_SetVar2. 6. The Tcl_CmdBuf structure has been eliminated, along with the procedures Tcl_CreateCmdBuf, Tcl_DeleteCmdBuf, and Tcl_AssembleCmd. Use dynamic strings instead. 7. Tcl_UnsetVar and Tcl_UnsetVar2 now return TCL_OK or TCL_ERROR instead of 0 or -1. 8. Tcl_UnixError has been renamed to Tcl_PosixError. 9. Tcl no longer redefines the library procedures "setenv", "putenv", and "unsetenv" by default. You have to set up special configuration in the Makefile if you want this. Below is a sampler of the most important new features in Tcl 7.0. Refer to the "changes" file for a complete list. 1. The "expr" command supports transcendental and other math functions, plus it allows you to type expressions in multiple arguments. Its numerics have also been improved in several ways (e.g. support for NaN). 2. The "format" command now supports XPG3 %n$ conversion specifiers. 3. The "exec" command supports many new kinds of redirection such as >> and >&, plus it allows you to leave out the space between operators like < and the file name. For processes put into the background, "exec" returns a list of process ids. 4. The "lsearch" command now supports regular expressions and exact matching. 5. The "lsort" command has several new switches to control the sorting process (e.g. numerical sort, user-provided sort function, reverse sort, etc.). 6. There's a new command "pid" that can be used to return the current process ids or the process ids from an open file that refers to a pipeline. 7. There's a new command "switch" that should now be used instead of "case". It supports regular expressions and exact matches, and also uses single patterns instead of pattern lists. "Case" is now deprecated, although it's been retained for compatibility. 8. A new dynamic string library has been added to make it easier to build up strings and lists of arbitrary length. See the manual entry "DString.3". 9. Variable handling has been improved in several ways: you can now use whole-array traces to create variables on demand, you can delete variables during traces, you can upvar to array elements, and you can retarget an upvar variable to stop through a sequence of variables. Also, there's a new library procedure Tcl_LinkVar that can be used to associate a C variable with a Tcl variable and keep them in sync. 10. New library procedures Tcl_SetCommandInfo and Tcl_GetCommandInfo allow you to set and get the clientData and callback procedure for a command. 11. Added "-errorinfo" and "-errorcode" options to "return" command; they allow much better error handling. 12. Made prompts in tclsh user-settable via "tcl_prompt1" and "tcl_prompt2" variables. 13. Added low-level support that is needed to handle signals: see Tcl_AsyncCreate, etc. 6. Tcl newsgroup ----------------- There is a network news group "comp.lang.tcl" intended for the exchange of information about Tcl, Tk, and related applications. Feel free to use the newsgroup both for general information questions and for bug reports. I read the newsgroup and will attempt to fix bugs and problems reported to it. 7. Tcl contributed archive -------------------------- Many people have created exciting packages and applications based on Tcl and made them freely available to the Tcl community. An archive of these contributions is kept on the machine harbor.ecn.purdue.edu. You can access the archive using anonymous FTP; the Tcl contributed archive is in the directory "pub/tcl". The archive also contains an FAQ ("frequently asked questions") document that provides solutions to problems that are commonly encountered by TCL newcomers. 8. Support and bug fixes ------------------------ I'm very interested in receiving bug reports and suggestions for improvements. Bugs usually get fixed quickly (particularly if they are serious), but enhancements may take a while and may not happen at all unless there is widespread support for them (I'm trying to slow the rate at which Tcl turns into a kitchen sink). It's almost impossible to make incompatible changes to Tcl at this point. The Tcl community is too large for me to provide much individual support for users. If you need help I suggest that you post questions to comp.lang.tcl. I read the newsgroup and will attempt to answer esoteric questions for which no-one else is likely to know the answer. In addition, Tcl support and training are available commercially from NeoSoft. For more information, send e-mail to "info@neosoft.com". 9. Tcl release organization --------------------------- Each Tcl release is identified by two numbers separated by a dot, e.g. 6.7 or 7.0. If a new release contains changes that are likely to break existing C code or Tcl scripts then the major release number increments and the minor number resets to zero: 6.0, 7.0, etc. If a new release contains only bug fixes and compatible changes, then the minor number increments without changing the major number, e.g. 7.1, 7.2, etc. If you have C code or Tcl scripts that work with release X.Y, then they should also work with any release X.Z as long as Z > Y. Beta releases have an additional suffix of the form bx. For example, Tcl 7.0b1 is the first beta release of Tcl version 7.0, Tcl 7.0b2 is the second beta release, and so on. A beta release is an initial version of a new release, used to fix bugs and bad features before declaring the release stable. Each new release will be preceded by one or more beta releases. I hope that lots of people will try out the beta releases and report problems back to me. I'll make new beta releases to fix the problems, until eventually there is a beta release that appears to be stable. Once this occurs I'll remove the beta suffix so that the last beta release becomes the official release. If a new release contains incompatibilities (e.g. 7.0) then I can't promise to maintain compatibility among its beta releases. For example, release 7.0b2 may not be backward compatible with 7.0b1. I'll try to minimize incompatibilities between beta releases, but if a major problem turns up then I'll fix it even if it introduces an incompatibility. Once the official release is made then there won't be any more incompatibilities until the next release with a new major version number. 10. Compiling on non-UNIX systems -------------------------------- The Tcl features that depend on system calls peculiar to UNIX (stat, fork, exec, times, etc.) are now separate from the main body of Tcl, which only requires a few generic library procedures such as malloc and strcpy. Thus it should be relatively easy to compile Tcl for non-UNIX machines such as MACs and DOS PC's, although a number of UNIX-specific commands will be absent (e.g. exec, time, and glob). See the comments at the top of Makefile for information on how to compile without the UNIX features.