Tcl

by John Ousterhout (and many others at Sun Microsystems and elsewhere)
john.ousterhout@eng.sun.com


1. Introduction
---------------

This directory and its descendants contain the sources and documentation
for Tcl, an embeddable scripting language.  The information here corresponds
to release 7.5.  The most important new feature in this release is support
for the PC and Mac platforms.  In addition, there are major new facilities
for supporting dynamic loading, multiple interpreters, and safe execution
of untrusted scripts.  This release also contains many bug fixes.  Tcl 7.5
should be backwards compatible with Tcl 7.4 (there are two small
incompatibilities described below, but they are relatively insignificant
and shouldn't affect most existing Tcl code and extensions).

2. Documentation
----------------

The best way to get started with Tcl is to read one of the introductory
books on Tcl:

    Tcl and the Tk Toolkit, by John Ousterhout,
    Addison-Wesley, 1994, ISBN 0-201-63337-X

    Practical Programming in Tcl and Tk, by Brent Welch,
    Prentice-Hall, 1995, ISBN 0-13-182007-9

The "doc" subdirectory in this release contains a complete set of reference
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 contains everything you should need to compile and run
Tcl under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
or Win 3.1 with Win32s).

Before trying to compile Tcl you should do the following things:

    (a) Check for a binary release.  Pre-compiled binary releases are
        available now for PCs and Macintoshes, and they may be available
	in the future for some flavors of UNIX.  Look in the FTP
	directory from which  you retrieved the base distribution to
	see if a suitable binary release is available.  If so, it will
	be much easier to install than the source release.

    (b) Check for patches.  Look in the FTP directory from which you
        retrieved the base distribution and see if there are files with
	names like tcl7.5p1.patch, tcl7.5p2patch, etc.  These files may
	also have .gz or .Z extensions to indicate compression.  If you find
	any patch files, apply them to the source directory in order
	from "p1" up.  To apply an uncompressed patch file such as
	tcl7.5p1.patch, invoke a shell command like the following from
	the directory containing this file:
	    patch -p < tcl7.5p1.patch
	If the patch file has a .gz extension, invoke a command like the
	following:
	    gunzip -c tcl7.5p1.patch.gz | patch -p
	If the patch file has a .Z extension, it was compressed with
	compress.  To apply it, invoke a command like the following:
	    zcat tcl7.5p1.patch.Z | patch -p

Once you've done this, change to the "unix" subdirectory if you're
compiling under UNIX, "win" if you're compiling under Windows, or
"mac" if you're compiling on a Macintosh.  Then follow the instructions
in the README file in that directory for compiling Tcl, installing it,
and running the test suite.

4. Additional release information
---------------------------------

There is now an official home for Tcl and Tk on the Web at the following
URL:
	http://www.smli.com/research/tcl
These Web pages include release updates, reports on bug fixes and
porting issues, and pointers to many other Tcl/Tk Web pages at other
sites.  Check them out!

5. Summary of changes in Tcl 7.5
--------------------------------

The main change for Tcl 7.5 is that Tcl now runs on Macintosh and
PC platforms as well as UNIX.  The PC port should support Windows 3.1
(with Win32s), Windows 95, and Windows NT.  This required a lot of
reorganization of the sources but it didn't require any changes to
Tcl's externally visible interfaces.

In addition to the ports, Tcl 7.5 also has four other new features:

    1. Dynamic loading.  There is now a "load" command for loading binary
    extensions into Tcl on the fly.  This works now on most of the major
    UNIX platforms (except AIX) as well as PCs and Macintoshes.  Support
    for other platforms should become available over time.  Two new "info"
    commands, "info sharedlibextension" and "info nameofexecutable", were
    also added as part of the dynamic loading implementation.  Dynamic
    loading is still incomplete in two ways:  (a) Tcl and Tk are not
    themselves available as shared libraries, and (b) there is no support
    for version management.  Both of these facilities should appear in
    the next Tcl release.
    
    2. Multiple interpreters and Safe-Tcl.  There is a new "interp" command
    that allows you to create multiple interpreters within a single application
    and set up communication between them with "aliases".  The mechanism also
    supports "safe" interpreters, which provide a generalized version of the
    security mechanisms in Borenstein and Rose's Safe-Tcl.  There are still
    a few missing security features, such as resource control and Tk support;
    these will be coming in a later release.
    
    3. There is an "AssocData" mechanism that allows extensions to store
    their own data in an interpreter and get called back when the interpreter
    is deleted.  This is visible at C level via the procedures Tcl_SetAssocData
    and Tcl_GetAssocData.

    5. When manual pages are installed, additional links are created for
    each of the procedures described in the manual page, so that it's
    easier to invoke the "man" command.

    6. There is a new variable "tcl_platform" with platform information.
    This is an associative array with elements like "os" and "machine"
    that contain various pieces of information about the platform.

Two minor incompatibilities were introduced by the changes.  These changes
are are obscure enough that they are unlikely to affect any existing code,
especially at the level of Tcl scripts:

    1. Tcl doesn't export any global C variables anymore, because this doesn't
    work with Windows DLLs.  The C variables tcl_AsyncReady and
    tcl_FileCloseProc have been replaced with procedures Tcl_AsyncReady()
    and Tcl_SetFileCloseProc().  The C variable tcl_RcFileName has been
    replaced with a Tcl variable tcl_rcFileName.
    
    2. Files are no longer shared between interpreters by default:  if a
    file is opened in one interpreter, it cannot normally be used in other
    interpreters.  However, the new procedure Tcl_ShareHandle allows files
    to be shared between interpreters if requested explicitly.

For a complete list of all changes in this release, see the file "changes"
in this directory.

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.
We read the newsgroup and will attempt to fix bugs and problems reported
to it.

When using comp.lang.tcl, please be sure that your e-mail return address
is correctly set in your postings.  This allows people to respond directly
to you, rather than the entire newsgroup, for answers that are not of
general interest.  A bad e-mail return address may prevent you from
getting answers to your questions.  You may have to reconfigure your news
reading software to ensure that it is supplying valid e-mail addresses.

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 ftp.aud.alcatel.com.  You can
access the archive using anonymous FTP;  the Tcl contributed archive is
in the directory "/tcl".  The archive also contains several FAQ ("frequently
asked questions") documents that provide solutions to problems commonly
encountered by TCL newcomers.

8. Support and bug fixes
------------------------

We're very interested in receiving bug reports and suggestions for
improvements.  We prefer that you send this information to the
comp.lang.tcl newsgroup rather than to any of us at Sun.  We'll see
anything on comp.lang.tcl, and in addition someone else who reads 
omp.lang.tcl may be able to offer a solution.  The normal turn-around
time for bugs is 2-4 weeks.  Enhancements may take longer and may not
happen at all unless there is widespread support for them (we're
trying to slow the rate at which Tcl turns into a kitchen sink).  It's
very difficult to make incompatible changes to Tcl at this point, due
to the size of the installed base.

When reporting bugs, please provide a short tclsh script that we can
use to reproduce the bug.  Make sure that the script runs with a
bare-bones tclsh and doesn't depend on any extensions or other
programs, particularly those that exist only at your site.  Also,
please include three additional pieces of information with the
script:
    (a) how do we use the script to make the problem happen (e.g.
	what things do we click on, in what order)?
    (b) what happens when you do these things (presumably this is
        undesirable)?
    (c) what did you expect to happen instead?

The Tcl community is too large for us to provide much individual
support for users.  If you need help we suggest that you post questions
to comp.lang.tcl.  We 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 (info@neosoft.com), Computerized Processes Unlimited
(gwl@cpu.com), and Data Kinetics (education@dkl.com).

9. Tcl version numbers
----------------------

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.

Alpha and beta releases have an additional suffix of the form a2 or b1.
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.  An alpha release is like a beta release,
except it's likely to need even more work before it's "ready for prime
time".  New releases are normally preceded by one or more alpha and beta
releases.  We hope that lots of people will try out the alpha and beta
releases and report problems.  We'll make new alpha/beta releases to fix
the problems, until eventually there is a beta release that appears to
be stable.  Once this occurs we'll make the final release.

We can't promise to maintain compatibility among alpha and beta releases.
For example, release 7.1b2 may not be backward compatible with 7.1b1, even
though the final 7.1 release will be backward compatible with 7.0.  This
allows us to change new features as we find problems during beta testing.
We'll try to minimize incompatibilities between beta releases, but if
a major problem turns up then we'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.
