382 lines
18 KiB
Plaintext
382 lines
18 KiB
Plaintext
Tcl
|
|
|
|
SCCS: @(#) README 1.52 97/11/20 12:43:16
|
|
|
|
1. Introduction
|
|
---------------
|
|
|
|
This directory and its descendants contain the sources and documentation
|
|
for Tcl, an embeddable scripting language. The information here
|
|
corresponds to release 8.0p2, which is the second patch update for Tcl
|
|
8.0. Tcl 8.0 is a major new release that replaces the core of the
|
|
interpreter with an on-the-fly bytecode compiler to improve execution
|
|
speed. It also includes several other new features such as namespaces
|
|
and binary I/O, plus many bug fixes. The compiler introduces a few
|
|
incompatibilities that may affect existing Tcl scripts; the
|
|
incompatibilities are relatively obscure but may require modifications
|
|
to some old scripts before they can run with this version. The compiler
|
|
introduces many new C-level APIs, but the old APIs are still supported.
|
|
See below for more details. This patch release fixes various bugs in
|
|
Tcl 8.0; there are no feature changes relative to Tcl 8.0.
|
|
|
|
2. Documentation
|
|
----------------
|
|
|
|
The best way to get started with Tcl is to read one of the introductory
|
|
books on Tcl:
|
|
|
|
Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
|
|
Prentice-Hall, 1997, ISBN 0-13-616830-2
|
|
|
|
Tcl and the Tk Toolkit, by John Ousterhout,
|
|
Addison-Wesley, 1994, ISBN 0-201-63337-X
|
|
|
|
Exploring Expect, by Don Libes,
|
|
O'Reilly and Associates, 1995, ISBN 1-56592-090-2
|
|
|
|
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
|
|
|
|
There is also an official home for Tcl and Tk on the Web:
|
|
http://sunscript.sun.com
|
|
These Web pages include information about the latest releases, products
|
|
related to Tcl and Tk, reports on bug fixes and porting issues, HTML
|
|
versions of the manual pages, and pointers to many other Tcl/Tk Web
|
|
pages at other sites. Check them out!
|
|
|
|
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, Macintoshes, and several flavors of UNIX.
|
|
Binary releases are much easier to install than source releases.
|
|
To find out whether a binary release is available for your
|
|
platform, check the home page for SunScript
|
|
(http://sunscript.sun.com) under "Tech Corner". Also, check in
|
|
the FTP directory from which you retrieved the base
|
|
distribution. Some of the binary releases are available freely,
|
|
while others are for sale.
|
|
|
|
(b) Make sure you have the most recent patch release. Look in the
|
|
FTP directory from which you retrieved this distribution to see
|
|
if it has been updated with patches. Patch releases fix bugs
|
|
without changing any features, so you should normally use the
|
|
latest patch release for the version of Tcl that you want.
|
|
Patch releases are available in two forms. A file like
|
|
tcl8.0p2.tar.Z is a complete release for patch level 2 of Tcl
|
|
version 8.0. If there is a file with a higher patch level than
|
|
this release, just fetch the file with the highest patch level
|
|
and use it.
|
|
|
|
Patches are also available in the form of patch files that just
|
|
contain the changes from one patch level to another. These
|
|
files will have names like tcl8.0p1.patch, tcl8.0p2.patch, etc. They
|
|
may also have .gz or .Z extensions to indicate compression. To
|
|
use one of these files, you apply it to an existing release with
|
|
the "patch" program. Patches must be applied in order:
|
|
tcl8.0p1.patch must be applied to an unpatched Tcl 8.0 release
|
|
to produce a Tcl 8.0p1 release; tcl8.0p2.patch can then be
|
|
applied to Tcl8.0p1 to produce Tcl 8.0p2, and so on. To apply an
|
|
uncompressed patch file such as tcl8.0p1.patch, invoke a shell
|
|
command like the following from the directory containing this
|
|
file:
|
|
patch -p < tcl8.0p1.patch
|
|
If the patch file has a .gz extension, invoke a command like the
|
|
following:
|
|
gunzip -c tcl8.0p1.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 tcl8.0p1.patch.Z | patch -p
|
|
If you're applying a patch to a release that has already been
|
|
compiled, then before applying the patch you should cd to the
|
|
"unix" subdirectory and type "make distclean" to restore the
|
|
directory to a pristine state.
|
|
|
|
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. Summary of changes in Tcl 8.0
|
|
--------------------------------
|
|
|
|
Here are the most significant changes in Tcl 8.0. In addition to these
|
|
changes, there are several smaller changes and bug fixes. See the file
|
|
"changes" for a complete list of all changes.
|
|
|
|
1. Bytecode compiler. The core of the Tcl interpreter has been
|
|
replaced with an on-the-fly compiler that translates Tcl scripts to
|
|
byte codes; a new interpreter then executes the byte codes. In
|
|
earlier versions of Tcl, strings were used as a universal
|
|
representation; in Tcl 8.0 strings are replaced with Tcl_Obj
|
|
structures ("objects") that can hold both a string value and an
|
|
internal form such as a binary integer or compiled bytecodes. The
|
|
new objects make it possible to store information in efficient
|
|
internal forms and avoid the constant translations to and from
|
|
strings that occurred with the old interpreter. We have not yet
|
|
converted all of Tcl to take full advantage of the compiler and
|
|
objects and have not converted any of Tk yet, but even so you
|
|
should see speedups of 2-3x on many programs and you may see
|
|
speedups as much as 10-20x in some cases (such as code that
|
|
manipulates long lists). Future releases should achieve even
|
|
greater speedups. The compiler introduces only a few minor changes
|
|
at the level of Tcl scripts, but it introduces many new C APIs for
|
|
managing objects. See, for example, the manual entries doc/*Obj*.3.
|
|
|
|
2. Namespaces. There is a new namespace mechanism based on the
|
|
namespace implementation by Michael McLennan of Lucent Technologies.
|
|
This includes new "namespace" and "variable" commands. There are
|
|
many new C APIs associated with namespaces, but they will not be
|
|
exported until Tcl 8.1. Note: the syntax of the namespace command
|
|
has been changed slightly since the b1 release. See the changes
|
|
file for details.
|
|
|
|
3. Binary I/O. The new object system in Tcl 8.0 supports binary
|
|
strings (internally, strings are counted in addition to being null
|
|
terminated). There is a new "binary" command for inserting and
|
|
extracting data to/from binary strings. Commands such as "puts",
|
|
"gets", and "read" commands now operate correctly on binary data.
|
|
There is a new variable tcl_platform(byteOrder) to identify the
|
|
native byte order for the current host.
|
|
|
|
4. Random numbers. The "expr" command now contains a random number
|
|
generator, which can be accessed via the "rand()" and "srand()" math
|
|
functions.
|
|
|
|
5. Safe-Tcl enhancements. There is a new "hidden command"
|
|
mechanism, implemented with the Tcl commands "interp hide", "interp
|
|
expose", "interp invokehidden", and "interp hidden" and the C APIs
|
|
Tcl_HideCommand and Tcl_ExposeCommand. There is now support for
|
|
safe packages and extension loading, including new library
|
|
procedures such as safe::interpCreate (see the manual entry safe.n
|
|
for details).
|
|
|
|
6. There is a new package "registry" available under Windows for
|
|
accessing the Windows registry.
|
|
|
|
7. There is a new command "file attributes" for getting and setting
|
|
things like permissions and owner. There is also a new command
|
|
"file nativename" for getting back the platform-specific name for a
|
|
particular file.
|
|
|
|
8. There is a new "fcopy" command to copy data between channels.
|
|
This replaces and improves upon the not-so-secret unsupported old
|
|
command "unsupported0".
|
|
|
|
9. There is a new package "http" for doing GET, POST, and HEAD
|
|
requests via the HTTP/1.0 protocol. See the manual entry http.n
|
|
for details.
|
|
|
|
10. There are new library procedures for finding word breaks in
|
|
strings. See the manual entry library.n for details.
|
|
|
|
11. There are new C APIs Tcl_Finalize (for cleaning up before
|
|
unloading the Tcl DLL) and Tcl_Ungets for pushing bytes back into a
|
|
channel's input buffer.
|
|
|
|
12. Tcl now supports serial I/O devices on Windows and Unix, with a
|
|
new fconfigure -mode option. The Windows driver does not yet
|
|
support event-driven I/O.
|
|
|
|
13. The lsort command has new options -dictionary and -index. The
|
|
-index option allows for very rapid sorting based on an element
|
|
of a list.
|
|
|
|
14. The event notifier has been completely rewritten (again). It
|
|
should now allow Tcl to use an external event loop (like Motif's)
|
|
when it is embedded in other applications. No script-level
|
|
interfaces have changed, but many of the C APIs have.
|
|
|
|
Tcl 8.0 introduces the following incompatibilities that may affect Tcl
|
|
scripts that worked under Tcl 7.6 and earlier releases:
|
|
|
|
1. Variable and command names may not include the character sequence
|
|
"::" anymore: this sequence is now used as a namespace separator.
|
|
|
|
2. The semantics of some Tcl commands have been changed slightly to
|
|
maximize performance under the compiler. These incompatibilities
|
|
are documented on the Web so that we can keep the list up-to-date.
|
|
See the URL http://www.sunlabs.com/research/tcl/compiler.html.
|
|
|
|
3. 2-digit years are now parsed differently by the "clock" command
|
|
to handle year 2000 issues better (years 00-38 are treated as
|
|
2000-2038 instead of 1900-1938).
|
|
|
|
4. The old Macintosh commands "cp", "mkdir", "mv", "rm", and "rmdir"
|
|
are no longer supported; all of these features are now available on
|
|
all platforms via the "file" command.
|
|
|
|
5. The variable tcl_precision is now shared between interpreters
|
|
and defaults to 12 digits instead of 6; safe interpreters cannot
|
|
modify tcl_precision. The new object system in Tcl 8.0 causes
|
|
floating-to-string conversions (and the associated rounding) to
|
|
occur much less often than in Tcl 7.6, which can sometimes cause
|
|
behavioral changes.
|
|
|
|
6. The C APIs associated with the notifier have changed substantially.
|
|
|
|
7. The procedures Tcl_CreateModalTimeout and Tcl_DeleteModalTimeout
|
|
have been removed.
|
|
|
|
8. Tcl_CreateFileHandler and Tcl_DeleteFileHandler now take Unix
|
|
fd's and are only supported on the Unix platform
|
|
|
|
9. The C APIs for creating channel drivers have changed as part of
|
|
the new notifier implementation. The Tcl_File interfaces have been
|
|
removed. Tcl_GetChannelFile has been replaced with
|
|
Tcl_GetChannelHandle. Tcl_MakeFileChannel now takes a platform-
|
|
specific file handle. Tcl_DriverGetOptionProc procedures now take
|
|
an additional interp argument.
|
|
|
|
5. 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.
|
|
|
|
6. Tcl contributed archive
|
|
--------------------------
|
|
|
|
Many people have created exciting packages and applications based on Tcl
|
|
and/or Tk and made them freely available to the Tcl community. An archive
|
|
of these contributions is kept on the machine ftp.neosoft.com. You
|
|
can access the archive using anonymous FTP; the Tcl contributed archive is
|
|
in the directory "/pub/tcl". The archive also contains several FAQ
|
|
("frequently asked questions") documents that provide solutions to problems
|
|
that are commonly encountered by TCL newcomers.
|
|
|
|
7. Mailing lists
|
|
----------------
|
|
|
|
A couple of Mailing List have been set up to discuss Macintosh or
|
|
Windows related Tcl issues. In order to use these Mailing Lists you
|
|
must have access to the internet. If you have access to the WWW the
|
|
home pages for these mailing lists are located at the following URLs:
|
|
|
|
http://www.sunlabs.com/research/tcl/lists/mactcl-list.html
|
|
|
|
-and-
|
|
|
|
http://www.sunlabs.com/research/tcl/lists/wintcl-list.html
|
|
|
|
The home pages contain information about the lists and an HTML archive
|
|
of all the past messages on the list. To subscribe send a message to:
|
|
|
|
listserv@sunlabs.sun.com
|
|
|
|
In the body of the message (the subject will be ignored) put:
|
|
|
|
subscribe mactcl Joe Blow
|
|
|
|
Replacing Joe Blow with your real name, of course. (Use wintcl
|
|
instead of mactcl if your interested in the Windows list.) If you
|
|
would just like to receive more information about the list without
|
|
subscribing put the line:
|
|
|
|
information mactcl
|
|
|
|
in the body instead (or wintcl).
|
|
|
|
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
|
|
comp.lang.tcl may be able to offer a solution. The normal turn-around
|
|
time for bugs is 3-6 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.
|
|
|
|
Patch releases have a suffix such as p1 or p2. These releases contain
|
|
bug fixes only. A patch release (e.g Tcl 7.6p2) should be completely
|
|
compatible with the base release from which it is derived (e.g. Tcl
|
|
7.6), and you should normally use the highest available patch release.
|