home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tcl2-73c.zip / tcl7.3 / README < prev    next >
Text File  |  1993-11-21  |  16KB  |  347 lines

  1. Tcl
  2.  
  3. by John Ousterhout
  4. University of California at Berkeley
  5. ouster@cs.berkeley.edu
  6.  
  7. 1. Introduction
  8. ---------------
  9.  
  10. This directory contains the sources and documentation for Tcl, an
  11. embeddable tool command language.  The information here corresponds
  12. to release 7.3.
  13.  
  14. 2. Documentation
  15. ----------------
  16.  
  17. The best way to get started with Tcl is to read the draft of my
  18. upcoming book on Tcl and Tk, which can be retrieved using anonymous
  19. FTP from the directory "ucb/tcl" on ftp.cs.berkeley.edu.  Part I of the
  20. book provides an introduction to writing Tcl scripts and Part III
  21. describes how to write C code that uses the Tcl C library procedures.
  22.  
  23. The "doc" subdirectory in this release contains a complete set of manual
  24. entries for Tcl.  Files with extension ".1" are for programs (for
  25. example, tclsh.1); files with extension ".3" are for C library procedures;
  26. and files with extension ".n" describe Tcl commands.  The file "doc/Tcl.n"
  27. gives a quick summary of the Tcl language syntax.  To print any of the man
  28. pages, cd to the "doc" directory and invoke your favorite variant of
  29. troff using the normal -man macros, for example
  30.  
  31.         ditroff -man Tcl.n
  32.  
  33. to print Tcl.n.  If Tcl has been installed correctly and your "man"
  34. program supports it, you should be able to access the Tcl manual entries
  35. using the normal "man" mechanisms, such as
  36.  
  37.         man Tcl
  38.  
  39. 3. Compiling and installing Tcl
  40. -------------------------------
  41.  
  42. This release should compile and run "out of the box" on any UNIX-like
  43. system that approximates POSIX, BSD, or System V.  I know that it runs
  44. on workstations from Sun, DEC, H-P, IBM, and Silicon Graphics, and on
  45. PC's running SCO UNIX and Xenix.  To compile Tcl, do the following:
  46.  
  47.     (a) Type "./configure" in this directory.  This runs a configuration
  48.     script created by GNU autoconf, which configures Tcl for your
  49.     system and creates a Makefile.  The configure script allows you
  50.     to customize the Tcl configuration for your site;  for details on
  51.     how you can do this, see the file "configure.info".
  52.  
  53.     (b) Type "make".  This will create a library archive called "libtcl.a"
  54.     and an interpreter application called "tclsh" that allows you to type
  55.     Tcl commands interactively or execute script files.
  56.  
  57.     (c) If the make fails then you'll have to personalize the Makefile
  58.         for your site or possibly modify the distribution in other ways.
  59.     First check the file "porting.notes" to see if there are hints
  60.     for compiling on your system.  If you need to modify Makefile,
  61.     there are comments at the beginning of it that describe the things
  62.     you might want to change and how to change them.
  63.  
  64.     (d) Type "make install" to install Tcl binaries and script files in
  65.         standard places.  You'll need write permission on /usr/local to
  66.     do this.  See the Makefile for details on where things get
  67.     installed.
  68.  
  69.     (e) At this point you can play with Tcl by invoking the "tclsh"
  70.     program and typing Tcl commands.  However, if you haven't installed
  71.     Tcl then you'll first need to set your TCL_LIBRARY variable to
  72.     hold the full path name of the "library" subdirectory.
  73.  
  74. If you have trouble compiling Tcl, I'd suggest looking at the file
  75. "porting.notes".  It contains information that people have sent me about
  76. changes they had to make to compile Tcl in various environments.  I make
  77. no guarantees that this information is accurate, complete, or up-to-date,
  78. but you may find it useful.  If you get Tcl running on a new configuration,
  79. I'd be happy to receive new information to add to "porting.notes".  I'm
  80. also interested in hearing how to change the configuration setup so that
  81. Tcl compiles on additional platforms "out of the box".
  82.  
  83. 4. Test suite
  84. -------------
  85.  
  86. There is a relatively complete test suite for all of the Tcl core in
  87. the subdirectory "tests".  To use it just type "make test" in this
  88. directory.  You should then see a printout of the test files processed.
  89. If any errors occur, you'll see a much more substantial printout for
  90. each error.  See the README file in the "tests" directory for more
  91. information on the test suite.
  92.  
  93. 5. Summary of changes in recent releases
  94. ----------------------------------------
  95.  
  96. Tcl 7.3 is a minor release that includes only one change relative to
  97. Tcl 7.1 (it fixes a portability problem that prevented tclMain.c from
  98. compiling on some machines due to a missing R_OK definition).  Tcl 7.3
  99. should be completely compatible with Tcl 7.1 and Tcl 7.0.
  100.  
  101. Tcl 7.2 was a mistake; it was withdrawn shortly after it was released.
  102.  
  103. Tcl 7.1 is a minor release that consists almost entirely of bug fixes.
  104. The only feature change is to allow no arguments in invocations of "list"
  105. and "concat".  7.1 should be completely compatible with 7.0.
  106.  
  107. Tcl 7.0 is a major new release that includes several new features
  108. and a few incompatible changes.  For a complete list of all changes
  109. to Tcl in chronological order, see the file "changes".  Those changes
  110. likely to cause compatibility problems with existing C code or Tcl
  111. scripts are specially marked.  The most important changes are
  112. summarized below.
  113.  
  114. Tcl configuration and installation has improved in several ways:
  115.  
  116.     1. GNU autoconf is now used for configuring Tcl prior to compilation.
  117.  
  118.     2. The "tclTest" program no longer exists.  It has been replaced by
  119.     "tclsh", which is a true shell-like program based around Tcl (tclTest
  120.     didn't really work very well as a shell).  There's a new program
  121.     "tcltest" which is the same as "tclsh" except that it includes a
  122.     few extra Tcl commands for testing purposes.
  123.  
  124.     3. A new procedure Tcl_AppInit has been added to separate all of the
  125.     application-specific initialization from the Tcl main program.  This
  126.     should make it easier to build new Tcl applications that include
  127.     extra packages.
  128.  
  129.     4. There are now separate manual entries for each of the built-in
  130.     commands.  The manual entry "Tcl.n", which used to describe all of
  131.     the built-ins plus many other things, now contains a terse but
  132.     complete description of the Tcl language syntax.
  133.  
  134. Here is a list of all incompatibilities that affect Tcl scripts:
  135.  
  136.     1. There have been several changes to backslash processing:
  137.     - Unknown backslash sequences such as "\*" are now replaced with
  138.       the following character (such as "*");  Tcl used to treat the
  139.       backslash as an ordinary character in these cases, so both the
  140.       backslash and the following character would be passed through.
  141.     - Backslash-newline now eats up any white space after the newline,
  142.       replacing the whole sequence with a single space character.  Tcl
  143.       used to just remove the backslash and newline.
  144.     - The obsolete sequences \Cx, \Mx, \CMx, and \e no longer get
  145.       special treatment.
  146.     - The "format" command no longer does backslash processing on
  147.       its input string.
  148.     You can invoke the shell command below to locate backslash uses that
  149.     may potentially behave differently under Tcl 7.0.  This command
  150.     will print all of the lines from the script files "*.tcl" that may
  151.     not work correctly under Tcl 7.0:
  152.     egrep '(\\$)|(\\[^][bfnrtv\0-9{}$ ;"])' *.tcl
  153.     In some cases the command may print lines that are actually OK.
  154.  
  155.     2. The "glob" command now returns only the names of files that
  156.     actually exist, and it only returns names ending in "/" for
  157.     directories.
  158.  
  159.     3. When Tcl prints floating-point numbers (e.g. in the "expr" command)
  160.     it ensures that the numbers contain a "." or "e" so that they don't
  161.     look like integers.
  162.  
  163.     4. The "regsub" command now overwrites its result variable in all cases.
  164.     If there is no match, then the source string is copied to the result.
  165.  
  166.     5. The "exec", "glob", "regexp", and "regsub" commands now include a
  167.     "--" switch;  if the first non-switch argument starts with a "-" then
  168.     there must be a "--" switch or the non-switch argument will be treated
  169.     as a switch.
  170.  
  171.     6. The keyword "UNIX" in the variable "errorCode" has been changed to
  172.     "POSIX".
  173.  
  174.     7. The "format" and "scan" commands no longer support capitalized
  175.     conversion specifiers such as "%D" that aren't supported by ANSI
  176.     sprintf and sscanf.
  177.  
  178. Here is a list of all of the incompatibilities that affect C code that
  179. uses the Tcl library procedures.  If you use an ANSI C compiler then
  180. any potential problems will be detected when you compile your code:  if
  181. your code compiles cleanly then you don't need to worry about anything.
  182.  
  183.     1. Tcl_TildeString now takes a dynamic string as an argument, which is
  184.     used to hold the result.
  185.  
  186.     2. tclHash.h has been eliminated;  its contents are now in tcl.h.
  187.  
  188.     3. The Tcl_History command has been eliminated:  the "history" command
  189.     is now automatically part of the interpreter.
  190.  
  191.     4. The Tcl_Fork and Tcl_WaitPids procedures have been deleted (just
  192.     use fork and waitpid instead).
  193.  
  194.     5. The "flags" and "termPtr" arguments to Tcl_Eval have been eliminated,
  195.     as has the "noSep" argument to Tcl_AppendElement and the TCL_NO_SPACE
  196.     flag for Tcl_SetVar and Tcl_SetVar2.
  197.  
  198.     6. The Tcl_CmdBuf structure has been eliminated, along with the procedures
  199.     Tcl_CreateCmdBuf, Tcl_DeleteCmdBuf, and Tcl_AssembleCmd.  Use dynamic
  200.     strings instead.
  201.  
  202.     7. Tcl_UnsetVar and Tcl_UnsetVar2 now return TCL_OK or TCL_ERROR instead
  203.     of 0 or -1.
  204.  
  205.     8. Tcl_UnixError has been renamed to Tcl_PosixError.
  206.  
  207.     9. Tcl no longer redefines the library procedures "setenv", "putenv",
  208.     and "unsetenv" by default.  You have to set up special configuration
  209.     in the Makefile if you want this.
  210.  
  211. Below is a sampler of the most important new features in Tcl 7.0.  Refer
  212. to the "changes" file for a complete list.
  213.  
  214.     1. The "expr" command supports transcendental and other math functions,
  215.     plus it allows you to type expressions in multiple arguments.  Its
  216.     numerics have also been improved in several ways (e.g. support for
  217.     NaN).
  218.  
  219.     2. The "format" command now supports XPG3 %n$ conversion specifiers.
  220.  
  221.     3. The "exec" command supports many new kinds of redirection such as
  222.     >> and >&, plus it allows you to leave out the space between operators
  223.     like < and the file name.  For processes put into the background,
  224.     "exec" returns a list of process ids.
  225.  
  226.     4. The "lsearch" command now supports regular expressions and exact
  227.     matching.
  228.  
  229.     5. The "lsort" command has several new switches to control the
  230.     sorting process (e.g. numerical sort, user-provided sort function,
  231.     reverse sort, etc.).
  232.  
  233.     6. There's a new command "pid" that can be used to return the current
  234.     process ids or the process ids from an open file that refers to a
  235.     pipeline.
  236.  
  237.     7. There's a new command "switch" that should now be used instead
  238.     of "case".  It supports regular expressions and exact matches, and
  239.     also uses single patterns instead of pattern lists.  "Case" is
  240.     now deprecated, although it's been retained for compatibility.
  241.  
  242.     8. A new dynamic string library has been added to make it easier to
  243.     build up strings and lists of arbitrary length.  See the manual entry
  244.     "DString.3".
  245.  
  246.     9. Variable handling has been improved in several ways:  you can
  247.     now use whole-array traces to create variables on demand, you can
  248.     delete variables during traces, you can upvar to array elements,
  249.     and you can retarget an upvar variable to stop through a sequence
  250.     of variables.  Also, there's a new library procedure Tcl_LinkVar
  251.     that can be used to associate a C variable with a Tcl variable and
  252.     keep them in sync.
  253.  
  254.     10. New library procedures Tcl_SetCommandInfo and Tcl_GetCommandInfo
  255.     allow you to set and get the clientData and callback procedure for
  256.     a command.
  257.  
  258.     11. Added "-errorinfo" and "-errorcode" options to "return" command;
  259.     they allow much better error handling.
  260.  
  261.     12. Made prompts in tclsh user-settable via "tcl_prompt1" and
  262.     "tcl_prompt2" variables.
  263.  
  264.     13. Added low-level support that is needed to handle signals:  see
  265.     Tcl_AsyncCreate, etc.
  266.  
  267. 6. Tcl newsgroup
  268. -----------------
  269.  
  270. There is a network news group "comp.lang.tcl" intended for the exchange
  271. of information about Tcl, Tk, and related applications.  Feel free to use
  272. the newsgroup both for general information questions and for bug reports.
  273. I read the newsgroup and will attempt to fix bugs and problems reported
  274. to it.
  275.  
  276. 7. Tcl contributed archive
  277. --------------------------
  278.  
  279. Many people have created exciting packages and applications based on Tcl
  280. and made them freely available to the Tcl community.  An archive of these
  281. contributions is kept on the machine harbor.ecn.purdue.edu.  You can
  282. access the archive using anonymous FTP;  the Tcl contributed archive is
  283. in the directory "pub/tcl".  The archive also contains an FAQ ("frequently
  284. asked questions") document that provides solutions to problems that
  285. are commonly encountered by TCL newcomers.
  286.  
  287. 8. Support and bug fixes
  288. ------------------------
  289.  
  290. I'm very interested in receiving bug reports and suggestions for
  291. improvements.  Bugs usually get fixed quickly (particularly if they
  292. are serious), but enhancements may take a while and may not happen at
  293. all unless there is widespread support for them (I'm trying to slow
  294. the rate at which Tcl turns into a kitchen sink).  It's almost impossible
  295. to make incompatible changes to Tcl at this point.
  296.  
  297. The Tcl community is too large for me to provide much individual
  298. support for users.  If you need help I suggest that you post questions
  299. to comp.lang.tcl.  I read the newsgroup and will attempt to answer
  300. esoteric questions for which no-one else is likely to know the answer.
  301. In addition, Tcl support and training are available commercially from
  302. NeoSoft.  For more information, send e-mail to "info@neosoft.com".
  303.  
  304. 9. Tcl release organization
  305. ---------------------------
  306.  
  307. Each Tcl release is identified by two numbers separated by a dot, e.g.
  308. 6.7 or 7.0.  If a new release contains changes that are likely to break
  309. existing C code or Tcl scripts then the major release number increments
  310. and the minor number resets to zero: 6.0, 7.0, etc.  If a new release
  311. contains only bug fixes and compatible changes, then the minor number
  312. increments without changing the major number, e.g. 7.1, 7.2, etc.  If
  313. you have C code or Tcl scripts that work with release X.Y, then they
  314. should also work with any release X.Z as long as Z > Y.
  315.  
  316. Beta releases have an additional suffix of the form bx.  For example,
  317. Tcl 7.0b1 is the first beta release of Tcl version 7.0, Tcl 7.0b2 is
  318. the second beta release, and so on.  A beta release is an initial
  319. version of a new release, used to fix bugs and bad features before
  320. declaring the release stable.  Each new release will be preceded by
  321. one or more beta releases.  I hope that lots of people will try out
  322. the beta releases and report problems back to me.  I'll make new beta
  323. releases to fix the problems, until eventually there is a beta release
  324. that appears to be stable.  Once this occurs I'll remove the beta
  325. suffix so that the last beta release becomes the official release.
  326.  
  327. If a new release contains incompatibilities (e.g. 7.0) then I can't
  328. promise to maintain compatibility among its beta releases.  For example,
  329. release 7.0b2 may not be backward compatible with 7.0b1.  I'll try
  330. to minimize incompatibilities between beta releases, but if a major
  331. problem turns up then I'll fix it even if it introduces an
  332. incompatibility.  Once the official release is made then there won't
  333. be any more incompatibilities until the next release with a new major
  334. version number.
  335.  
  336. 10. Compiling on non-UNIX systems
  337. --------------------------------
  338.  
  339. The Tcl features that depend on system calls peculiar to UNIX (stat,
  340. fork, exec, times, etc.) are now separate from the main body of Tcl,
  341. which only requires a few generic library procedures such as malloc
  342. and strcpy.  Thus it should be relatively easy to compile Tcl for
  343. non-UNIX machines such as MACs and DOS PC's, although a number of
  344. UNIX-specific commands will be absent (e.g.  exec, time, and glob).
  345. See the comments at the top of Makefile for information on how to
  346. compile without the UNIX features.
  347.