path: root/contrib/tcl/README
diff options
authorPoul-Henning Kamp <phk@FreeBSD.org>1996-06-26 06:06:43 +0000
committerPoul-Henning Kamp <phk@FreeBSD.org>1996-06-26 06:06:43 +0000
commit403acdc0da2969f284b74b720692585bfc676190 (patch)
tree4d70f77f44120e6541d1418223baf06562774975 /contrib/tcl/README
Tcl 7.5, various makefiles will be updated to use these sources as soonvendor/tcl/7.5
as I get these back down to my machine.
Notes: svn path=/vendor/tcl/dist/; revision=16756 svn path=/vendor/tcl/7.5/; revision=16758; tag=vendor/tcl/7.5
Diffstat (limited to 'contrib/tcl/README')
1 files changed, 331 insertions, 0 deletions
diff --git a/contrib/tcl/README b/contrib/tcl/README
new file mode 100644
index 000000000000..ea654094ca0b
--- /dev/null
+++ b/contrib/tcl/README
@@ -0,0 +1,331 @@
+by John Ousterhout (and many others at Sun Microsystems and elsewhere)
+SCCS: @(#) README 1.29 96/04/19 11:42:58
+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 dynamic loading, package and version management, multiple interpreters,
+safe execution of untrusted scripts, and a new I/O system that supports
+nonblocking I/O and sockets. This release also contains many bug fixes.
+Tcl 7.5 should be backwards compatible with Tcl 7.4 scripts (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
+ 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://www.sunlabs.com/research/tcl
+These Web pages include release updates, 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 and Macintoshes, and they may be available
+ in the future for some 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 the Sun Tcl/Tk project (http://www.sunlabs.com/research/tcl)
+ and also check in the FTP directory from which you retrieved the
+ base distribution.
+ (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.5p2.patch, 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
+ 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 7.5
+The most important change for Tcl 7.5 is that Tcl now runs on Macintosh
+and PC platforms as well as UNIX. The PC port runs under 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 many other new features.
+The following feature changes have occurred since Tcl 7.4:
+ 1. Dynamic loading. There is a new "load" command for loading binary
+ extensions into Tcl on the fly. This works now on most of the major
+ UNIX platforms as well as PCs and Macintoshes. Three new "info"
+ commands, "info loaded", "info sharedlibextension", and
+ "info nameofexecutable", were also added as part of the dynamic loading
+ implementation. You can also create Tcl and Tk themselves as shared
+ libraries with the --enable-shared switch to the configure script.
+ 2. Packages and versions. There is a new "package" command for
+ package and version management. See the manual entries for "package"
+ and "pkg_mkIndex" for details on how to use it. There are also
+ C APIs to the package mechanism. See PkgRequire.3.
+ 3. 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. You can use
+ "load" to add extensions (including Tk) into slave interpreters.
+ 4. The event loop from Tk has been moved to Tcl. Tcl now has commands
+ "after", "fileevent", "update", and "vwait" (which replaces tkwait).
+ The "tkerror" command has been renamed to "bgerror". "Tkerror" is
+ still supported for backwards compatibility, but you should switch ASAP
+ to using "bgerror" instead. Many C procedures that used to be in Tk
+ have been moved to Tcl and renamed, such as Tcl_DoOneEvent, Tcl_DoWhenIdle,
+ Tcl_CreateFileHandler, and Tcl_CreateTimerHandler.
+ 5. Tcl has a whole new I/O system. All of the Tcl commands like
+ "open" and "puts" should continue to operate as before, but there
+ is a totally new implementation that doesn't use the C stdio library:
+ - The new I/O system is more portable, and it can be extended
+ with new kinds of I/O channels; see CrtChannel.3 for details.
+ - Nonblocking I/O is supported on all platforms and there is a
+ new command "fconfigure" to enable it and other channel options;
+ see fconfigure.n for details. There is also a new "fblocked"
+ command.
+ - The I/O system automatically translates between different
+ end-of-line representations (such as CR on Macs and CRLF on
+ PC's) to the newline form used in UNIX and in all Tcl scripts;
+ the "fconfigure" command can be used to control this feature.
+ - There is a set of C APIs for manipulating Tcl_Channel's, which
+ are analogous to UNIX FILE's. The C procedures have roughly the
+ same functionality as the stdio procedures. See OpenFileChnl.3,
+ CrtCloseHdlr.3, and CrtChnlHdlr.3 for details.
+ - There is a new structure Tcl_File that provides platform-
+ independent access to file handles such as UNIX fd's. See
+ GetFile.3 for details.
+ - There are new procedures Tcl_GetErrno and Tcl_SetErrno for
+ accessing the "errno" variable in a safe and portable fashion.
+ See SetErrno.3.
+ 6. There are new commands "file split", "file join", and "file pathtype",
+ which make it possible to handle file names in a way that will work on
+ all platforms. See the manual entries file.n and filename.n for
+ details.
+ 7. There is a new "socket" command for network communication via
+ TCP sockets. It works for both the client and server sides. There
+ is also C-level support for sockets; see OpenTcp.3.
+ 8. There is a new "clock" command, which contains the functionality
+ of the TclX clock-handling commands.
+ 9. The "foreach" command has been generalized significantly to support
+ multiple lists and multiple variables iterating over each list.
+ 10. There is a new "notifier" mechanism, which was added as part of
+ the ports. This allows the basic mechanisms for reporting events
+ to be implemented in different ways on different platforms. It
+ may also be useful for other purposes, such as merging the Tk and
+ Xt event loops so that Tk and Xt widgets can coexist in a single
+ application. See the manual entry Notifier.3 for more information.
+ 11. 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.
+ 12. 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.
+ 13. 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.
+ 14. There is a new procedure Tcl_CreateExitHandler that you can use to
+ make sure a C procedure is called before the Tcl application exits.
+ 15. There is a new procedure Tcl_UpdateLinkedVar to force the Tcl-level
+ variable to be updated after you've changed the corresponding C-level
+ variable.
+ 16. The procedures Tk_Preserve, Tk_Release, and Tk_EventuallyFree
+ have been moved from Tk to Tcl and given names like Tcl_Preserve.
+Three incompatibilities were introduced by the changes. All of these
+are at C-level, and only the first one should have much impact. Existing
+scripts for Tcl 7.4 should run unchanged under Tcl 7.5.
+ 1. The procedure Tcl_EnterFile no longer exists. However, a new
+ procedure Tcl_MakeFileChannel provides similar functionality.
+ Tcl_GetOpenFile still exists but only works under UNIX.
+ Tcl_CreatePipeline also remains, but it too works only under UNIX
+ now; use Tcl_OpenCommandChannel for better portability.
+ 2. 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 (use Tcl_SetVar to set the
+ Tcl variable, instead of assigning to the old C variable).
+ 3. 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.
+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. 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
+ (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).
+8. 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.