cvs.zerfleddert.de Git - micropolis/blob - src/tcl/readme.txt

   1 Tcl
   2
   3 by John Ousterhout
   4 University of California at Berkeley
   5 ouster@sprite.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 6.4.  This release is identical to the 6.3 release except
  13 for a few bug fixes and one new feature (the Tcl_GlobalEval procedure).
  14 The file "changes" has a complete list of all changes made to Tcl,
  15 with incompatible changes specially marked. Tcl 6.4 has no incompatible
  16 changes relative to 6.3.
  17
  18 For an introduction to the facilities provided by Tcl, see the paper
  19 ``Tcl:  An Embeddable Command Language'', in the Proceedings of the
  20 1990 Winter USENIX Conference.  A copy of that paper is included here
  21 in Postscript form in the file "doc/usenix.ps" and in text form in the
  22 file "doc/usenix.text".  However, the paper corresponds to a much
  23 earlier version of Tcl (approximately version 3.0), so some details
  24 of the paper may not be correct anymore and there are many new features
  25 not documented in the paper.
  26
  27 2. Documentation
  28 ----------------
  29
  30 The "doc" subdirectory contains a complete set of manual entries
  31 for Tcl.  The file "doc/Tcl.man" gives an overall description of the
  32 Tcl language and describes the core Tcl commands.  The other ".man"
  33 files in "doc" describe the library procedures that Tcl provides for
  34 Tcl-based applications.  Read the "Tcl" man page first.  To print any
  35 of the man pages, cd to the "doc" directory and invoke your favorite
  36 variant of troff using the normal -man macros, for example
  37
  38                 ditroff -man <file>
  39
  40 where <file> is the name of the man page you'd like to print.
  41
  42 3. Machines supported
  43 ---------------------
  44
  45 If you follow the directions below, this release should compile
  46 and run on the following configurations either "out of the box"
  47 or with only trivial changes:
  48
  49     - Sun-3's, Sun-4's, SPARCstation-1's and SPARCstation-2's running
  50       many variants of SunOS, such as 4.1.
  51     - DECstation-3100's and DECstation-5000's running many versions of
  52       Ultrix, such as 2.0 and 4.2.
  53     - DEC VAXes running many versions of Ultrix or BSD UNIX.
  54     - Intel 386 based systems running SCO Unix 3.2v2.
  55     - Intel 386 based systems running SCO Xenix 2.3.3.
  56     - Intel 386 based systems running Bell-Tech (now Intel) Unix 3.2.0.
  57     - Silicon Graphics systems running IRIX 4.0.
  58     - Various H-P machines running versions of HP-UX such as 7.05
  59     - Sequent Symmetry running versions of Dynix/ptx such as v1.2.4
  60
  61 If you find problems running Tcl on any of the above configurations,
  62 please let me know.  Also, if you are able to compile Tcl and run the
  63 test suite successfully on configurations not listed above, please
  64 let me know and tell me what changes, if any, you needed to make to
  65 do it.  I'd like to keep the above list up-to-date and continue to
  66 improve the portability of Tcl.
  67
  68 Tcl can be used on many other configurations with only a few
  69 modifications.  The file "porting.notes" contains information sent to
  70 me about what it took to get Tcl to run on various other configurations.
  71 I make no guarantees that this information is accurate or complete, but
  72 you may find it useful.  If you get Tcl running on a new configuration,
  73 I'd be deligted to receive new information to add to "porting.notes".
  74
  75 4. Compiling Tcl
  76 ----------------
  77
  78 To compile Tcl on any of the configurations listed above, or systems
  79 similar to them, do the following:
  80
  81     (a) If your system isn't one of the ones listed above, look in the
  82         file "porting.notes" to see if your system is listed there.  This
  83         file contains additonal notes on getting Tcl to run on various
  84         other systems.
  85
  86     (b) Edit the "set" commands at the beginning of the file "config"
  87         if necessary to correspond to your system configuration (they
  88         should already be right for most versions of Unix).
  89
  90     (c) Type "./config" in the top-level directory. "Config" is a script
  91         that pokes around in your system to see if certain almost-standard
  92         things are missing (header files, library procedures, etc.);
  93         if your system doesn't seem to have them, it configures Tcl to
  94         use its own copies of these things instead (Tcl's copies are
  95         kept in the "compat" subdirectory).  Config prints out messages
  96         for all the substitutions it made.  You can ignore any of the
  97         messages unless they say "ERROR!!";  in this case something is
  98         fundamentally wrong and the config script couldn't handle your
  99         system configuration.
 100
 101     (d) Type "make" to compile the library.  This will create the Tcl
 102         library in "libtcl.a".  The Makefile should work without any
 103         modifications but you may wish to personalize it, e.g. to
 104         turn on compiler optimization.
 105
 106     (e) If the combination of "config" and "make" doesn't work for you,
 107         then I suggest the following approach:
 108             - Start again with a fresh copy of the distribution.
 109             - Set the #defines that appear at the very front of
 110               tclUnix.h (before the first #include) to correspond
 111               to your system.
 112             - Modify Makefile to set CC, CFLAGS, etc. for your system.
 113             - If things don't compile or don't link, then you may need
 114               to copy some of the .c or .h files from the "compat"
 115               directory into the main Tcl directory to compensate for
 116               files missing from your system.  Modify the COMPAT_OBJS
 117               definition in Makefile to include a .o name for each of
 118               the .c files that you copied up from the compat directory.
 119
 120     (f) Create a directory /usr/local/lib/tcl and copy all the files
 121         from the "library" subdirectory to /usr/local/lib/tcl.  Or,
 122         you can use some other directory as library, but you'll need
 123         to modify the Makefile to reflect this fact (change the
 124         TCL_LIBRARY definition).
 125
 126     (g) Type "make tclTest", which will create a simple test program that
 127         you can use to try out the Tcl facilities.  TclTest is just a
 128         main-program sandwich around the Tcl library.  It reads standard
 129         input until it reaches the end of a line where parentheses and
 130         backslashes are balanced, then sends everything it's read to the
 131         Tcl interpreter.  When the Tcl interpreter returns, tclTest prints
 132         the return value or error message.  TclTest defines a few other
 133         additional commands, most notably:
 134
 135                         echo arg arg ...
 136
 137         The "echo" command prints its arguments on standard output,
 138         separated by spaces.
 139
 140 5. Test suite
 141 -------------
 142
 143 There is a relatively complete test suite for all of the Tcl core in
 144 the subdirectory "tests".  To use it just type "make test" in this
 145 directory.  You should then see a printout of the test files processed.
 146 If any errors occur, you'll see a much more substantial printout for
 147 each error.  Tcl should pass the test suite cleanly on all of the
 148 systems listed in Section 3.  See the README file in the "tests"
 149 directory for more information on the test suite.
 150
 151 6. Compiling on non-UNIX systems
 152 --------------------------------
 153
 154 The Tcl features that depend on system calls peculiar to UNIX (stat,
 155 fork, exec, times, etc.) are now separate from the main body of Tcl,
 156 which only requires a few generic library procedures such as malloc
 157 and strcpy.  Thus it should be relatively easy to compile Tcl for
 158 these machines, although a number of UNIX-specific commands will
 159 be absent (e.g.  exec, time, and glob).  See the comments at the
 160 top of Makefile for information on how to compile without the UNIX
 161 features.
 162
 163 7. Special thanks
 164 -----------------
 165
 166 Mark Diekhans and Karl Lehenbauer of Santa Cruz Operation deserve special
 167 thanks for all their help during the development of Tcl 6.0.  Many of the
 168 new features in Tcl 6.0 were inspired by an enhanced version of Tcl 3.3
 169 called Extended Tcl 4.0, which was created by Mark, Karl, and Peter
 170 da Silva.  Mark and Karl explained these features to me and provided
 171 excellent (and challenging) feedback during the 6.0 development process.
 172 They were also a great help in finding and fixing portability problems.
 173 Without their ideas and assistance Tcl 6.0 would be much less powerful.
 174
 175 8. Support
 176 ----------
 177
 178 There is no official support organization for Tcl, and I can't promise
 179 to provide much hand-holding to people learning Tcl.  However, I'm very
 180 interested in receiving bug reports and suggestions for improvements.
 181 Bugs usually get fixed quickly (particularly if they are serious), but
 182 enhancements may take a while and may not happen at all unless there
 183 is widespread support for them.
 184
 185 9. Tcl newsgroup
 186 -----------------
 187
 188 There is a network news group "comp.lang.tcl" intended for the exchange
 189 of information about Tcl, Tk, and related applications.  Feel free to use
 190 this newsgroup both for general information questions and for bug reports.
 191 I read the newsgroup and will attempt to fix bugs and problems reported
 192 to it.