Subversion Repositories or1k

Tcl

RCS: @(#) $Id: README,v 1.1.1.1 2002-01-16 10:25:22 markom Exp $

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.0.4, which is the fourth patch update for Tcl

8.0. This patch provides compatibility with [incr Tcl] 3.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, plus it adds a few minor features to support the TclPro 1.0

tool set and [incr Tcl] 3.0.  Please check the changes file for details.

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, 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 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.0.4.tar.Z is a complete release for patch level 4 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 (some versions of patch require "-p0"):

            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. 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 .  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.4).

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, 8.0.3, and 8.0.4.  The alphas and betas

will still use the 'a' and 'b' letters in their tcl_patchLevel.