path: root/README

Tcl

RCS: @(#) $Id: README,v 1.1.2.5 1998/12/11 01:32:13 stanton Exp $

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

This directory and its descendants contain the sources and
documentation for Tcl, an embeddable scripting language.  The
information here constitutes the 8.1b1 release, which is the first beta
release for Tcl 8.1.  This release is mostly feature complete but may
have bugs and be missing some minor features.  This release is for
early adopters who are willing to help us find and fix problems.
Please let us know about any problems you uncover.

Tcl 8.1 includes four major new features: Unicode support (all internal
strings are now stored in UTF-8 form), a new regular expression matcher
with most of the Perl features, support for multithreading, and a new
message catalog package.  For details on features, incompatibilities, and
potential problems with this release, see the Tcl/Tk 8.1 Web page at
http://www.scriptics.com/software/8.1.html or refer to the "changes" file
in this directory, which contains a historical record of all changes to
Tcl.

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

Other books are listed at
http://www.scriptics.com/resource/doc/books/
http://www.tclconsortium.org/resources/books.html

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://www.scriptics.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, Mac OS, and Windows (either Windows NT or Windows 95).

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 Scriptics Tcl Resource Center
        (http://www.scriptics.com/resource).  Also, check in
        the FTP directory from which you retrieved the base
        distribution.

    (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.1.3.tar.Z is a complete release for patch level 3 of Tcl
	version 8.1.  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.1p1.patch, tcl8.1p2.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.1p1.patch must be applied to an unpatched Tcl 8.1 release
	to produce a Tcl 8.1p1 release;  tcl8.1p2.patch can then be
	applied to Tcl8.1p1 to produce Tcl 8.1p2, and so on. To apply an
	uncompressed patch file such as tcl8.1p1.patch, invoke a shell
	command like the following from the directory containing this
	file (some versions of patch require "-p0"):
	    patch -p < tcl8.1p1.patch
	If the patch file has a .gz extension, invoke a command like the
	following:
	    gunzip -c tcl8.1p1.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.1p1.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.1
--------------------------------

Here are the most significant changes in Tcl 8.1.  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. Internationalization. Tcl has undergone a major revision to
    support international character sets:

    All strings in Tcl are now represented in UTF-8 instead of ASCII,
    so that Tcl now supports the full Unicode character set.  The
    representation of ASCII characters is unchanged (in UTF-8 anything
    that looks like an ASCII character is an ASCII character), but
    characters with the high-order bit set, such as those in ISO-8859,
    are represented with multi-byte sequences, as are all Unicode
    characters with values greater than 127.  This change does not
    affect Tcl scripts but it does affect C code that parses strings.
    Tcl automatically translates between UTF-8 and the normal encoding
    for the platform during interactions with the system.

    In Tcl scripts the backslash sequence \u can be used to enter
    16-bit Unicode characters.  \o and \x generate only 8-bit
    characters as before.

    There is a new "encoding" command that allows scripts to determine
    what encodings are available as well as to convert strings between
    different encodings.  The fconfigure command now supports a
    -encoding option for specifying the encoding of an open file or
    socket.  Tcl will automatically translate between the specified
    encoding and UTF-8 during I/O.

    There are several new C APIs that support UTF-8 and various
    encodings.  See the manual entry Utf.3 for procedures that
    translate between Unicode and UTF-8 and manipulate UTF-8 strings.
    See Encoding.3 for procedures that create new encodings and
    translate between encodings.  See ToUpper.3 for procedures that
    perform case conversions on UTF-8 strings.

    2. Binary data.  Binary data is handled differently in Tcl 8.1
    than in Tcl 8.0.  Tcl 8.1 uses the UTF-8 facilities to represent
    binary data: the character value zero is represented with a
    multi-byte sequence, so that (once again) strings in Tcl 8.1 never
    contain null bytes.  This means that binary data is now accepted
    everywhere in Tcl and Tk (in Tcl 8.0 the support for binary data
    was incomplete).  If you have C code that needs to manipulate the
    bytes of binary data (as opposed to just passing the data through)
    you should use a new object type called "byte array".  See the
    manual entry ByteArrObj.3 for information about procedures such as
    Tcl_GetByteArrayFromObj.

    3. Regular expressions.  Tcl 8.1 contains a brand new
    implementation of regular expressions from Henry Spencer.  The
    regular expression syntax has been greatly expanded to include
    most of the features in Perl.  In addition, the regexp engine
    supports Unicode and binary data.  See the doc/regexp.n manual
    entry for more details.

    4. Threads.  If configured with the --enable-threads flag, Tcl can
    now be compiled for use in a multi-threaded application.
    Individual threads are allowed to use one or more interpreters as
    long as each interpreter (and any slave interpreters) is only
    accessed by one thread.  Each thread runs its own event loop, and
    you can post events to other threads. There are new C APIs for
    mutexes, condition variables, and thread local storage.  See the
    doc/Thread.3 manual entry for more details.  Tk 8.1 is not yet
    multi-thread safe.  There is not yet support for tcl level use of
    threading except for a test command. (Compile tcltest and try
    testthread.)

    5. Message catalog. There is a new message catalog package which makes
    it easy to localize the strings in a script.  See the doc/msgcat.n
    manual entry for more details.

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. Tcl Resource Center
----------------------
Visit http://www.scritics.com/resource/ to see an annotated index of
many Tcl resources available on the World Wide Web.  This includes
papers, books, and FAQs, as well as extensions, applications, binary
releases, and patches.  You can contribute patches by sending them
to <patches@scriptics.com>.  You can also recommend more URLs for the
resource center using the forms labeled "Add a Resource".

8. 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.  To subscribe send a message to:
	
	wintcl-request@tclconsortium.org
	mactcl-request@tclconsortium.org
	
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).

9. 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 Scriptics.  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
Scriptics (info@scriptics.com), NeoSoft (info@neosoft.com),
Computerized Processes Unlimited (gwl@cpu.com),
and Data Kinetics (education@dkl.com).

10. Tcl version numbers
----------------------

You can test the current version of Tcl by examining the
tcl_version and tcl_patchLevel variables.  The tcl_patchLevel
variable follows the naming rules outlined below (e.g., 8.0.3).
The tcl_version just has the major.minor numbers in it (e.g., 8.0)

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.

(Note: This compatibility is true for Tcl scripts, but historically the Tcl
C APIs have changed enough between releases that you may need to work a bit to
upgrade extensions.)

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.

As of 8.0.3, the patch releases use a second . instead of 'p'.  So, the
8.0 release went to 8.0p1, 8.0p2, and 8.0.3.  The alphas and betas will
still use the 'a' and 'b' letters in their tcl_patchLevel.