archie/tcl7.3/README

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.