cvs.zerfleddert.de Git - micropolis/blob - src/tclx/readme

   1
   2               *** README.EXTD - README file for Extended Tcl ***
   3
   4
   5 EXTENDED TCL
   6 ============
   7
   8     Extended Tcl (TclX), defines a set of extensions to Tcl 6.4, the Tool
   9 Command Language invented by Dr. John Ousterhout of the University of
  10 California at Berkeley.  Tcl is a powerful, yet simple embeddable programming
  11 language.  Extended Tcl is oriented towards system programming tasks, with
  12 many additional interfaces to the Unix operating system, It is upwardly
  13 compatible with Tcl 6.4.  You take the Extended Tcl package, add it to Tcl
  14 6.4, and from that you get Extended Tcl.  (Berkeley Tcl is not included in
  15 this distribution, obtain it from sprite.berkeley.edu).
  16
  17    Support is also included for building a Tk wish shell with the Extended Tcl
  18 command set.
  19
  20     Extended Tcl was designed and implemented by Karl Lehenbauer
  21 (karl@NeoSoft.com) and Mark Diekhans (markd@Grizzly.com), with help in the
  22 early stages from Peter da Silva (peter@NeoSoft.com).
  23
  24    As with Berkeley Tcl, all of Extended Tcl is freely redistributable,
  25 including for commercial use and resale.
  26
  27
  28 FEATURES ADDED BY EXTENDED TCL
  29 ==============================
  30
  31    Here is a summary of the features added by Extended Tcl.  For more details
  32 on the commands and functionality provided by Extended Tcl, see the manual
  33 page man/TclX.man.
  34
  35     o A shell, which provides an environment for developing and executing
  36       Tcl programs.
  37
  38     o Advanced Tcl code library facility.
  39
  40     o General purpose commands which define new programming constructs,
  41       debugging and profiling facilities.
  42
  43     o Unix access commands provide access to many Unix system calls, including
  44       process management.
  45
  46     o File I/O commands provided added facilities for accessing and
  47       manipulating open files.
  48
  49     o File scanning facility that provides awk-like functionality.
  50
  51     o Math commands (random, sin, cos, etc).
  52
  53     o Extended list manipulation commands
  54
  55     o Keyed lists, a type of list that provided functionality similar to C
  56       structures.
  57
  58     o Extended string and character manipulation commands.
  59
  60
  61 NEW FEATURES IN THIS RELEASE
  62 ============================
  63
  64     o All known bugs are fixed.
  65
  66     o Configuration has been simplified.
  67
  68     o Improved support for Tk.  Including building a wish with signal support
  69       and building a Tk package library.
  70
  71     o All floating point functions (sin, cos, etc).  Now take expressions
  72       as arguments.  Floating point numbers will not be demoted to integers
  73       or lose precision.
  74
  75     o The standard Tcl expr command is patched so that floating point numbers
  76       do not get demoted to integers or lose precision.  This patch has been
  77       submitted to John Ousterhout.
  78
  79     o The character string manipulation commands take integer expressions
  80       for positions and lengths.
  81
  82     o The performance of the loading of package library indices and the
  83       loading of packages from the libraries has been improved.
  84
  85     o A performance profiling facility has been added.
  86
  87     o The alarm command will take fractions of a second on systems with the
  88       setitimer system call.
  89
  90     o Fcntl and fstat are easier to use.
  91
  92     o Better signal handling on systems with Posix signals.
  93
  94     o And more.  Review "TclX.man" and "CHANGES" for full details.
  95
  96 ON-LINE HELP
  97 ============
  98
  99     There is a help system included with Extended Tcl.  It contains some
 100 documentation on every command in Berkeley Tcl, and Extended Tcl.  You can
 101 invoke it interactively from within Extended Tcl by typing "help".
 102
 103     Once you bring Tcl up and have gotten it to pass all the tests, try typing
 104 "help help" to learn how to use help.
 105
 106 MANUAL PAGES
 107 ============
 108
 109     Man pages in nroff/troff format are provided for all of Tcl and the
 110 extensions in the directory tclX6.4c/man.  Start with the TclX.man manual.
 111
 112 EXTENDED TCL VERSION NAMING
 113 ===========================
 114
 115     Extended Tcl takes its version number from the corresponding version of
 116 Berkeley (Ousterhout) Tcl upon which it is based, with the addition of a
 117 trailing letter in case there are multiple releases of Extended Tcl within a
 118 single release of Berkeley Tcl.  This release is TclX 6.4c.
 119
 120 INTERFACING TCL AND C++
 121 =======================
 122
 123 C++ programmers can include the file "tcl++.h" to define C++ classes
 124 that can be used to access a Tcl interpreter.  This is based on Tcl
 125 C++ classes originally developed by Parag Patel.
 126
 127 TCL DIRECTORY HIERARCHY
 128 =======================
 129
 130 Here is an overview of the directory hierarchy:
 131
 132                              top_level_directory
 133
 134                           tcl6.4    tclX6.4c   tk2.3
 135
 136 The tcl6.4 directory contains Berkeley Tcl, unmodified and tk2.3 contains
 137 unmodified tk2.3, if you plan to use Tk  These locations are only suggested,
 138 they maybe changed by editing tclX6.4c/Config.mk.
 139
 140 The following directories are included under the tclX6.4c directory:
 141
 142     o config - Configuration files for various Unix versions.
 143
 144     o man - Unformated manual pages for TclX.
 145
 146     o src - The main source for TclX.
 147
 148     o osSupport - Library routines required by TclX that may not be available
 149       on all Unix versions.
 150
 151     o ucbsrc - A makefile and sed scripts used to modify source files that
 152       are supplied with UCB Tcl.  The files are modified with sed so you don't
 153       have to have patch to build Tcl, however context diffs are provided if
 154       problems occur porting to a new version of Tcl.
 155
 156     o tclsrc - Tcl source that is built into the Tcl package library.
 157
 158     o tcllib - Tcl source and runtime environment that is required to run TclX.
 159
 160     o tcllib/help - Help files for Tcl and TclX.
 161
 162     o tests - Tests for TclX.
 163
 164     o tkucbsrc - A makefile and sed scripts used to modify source files that
 165       are supplied with Tk to add in TclX functionality.  Context diffs are
 166       also provided.
 167
 168     o tksrc - A makefile that builds a version of the Tk wish shell containing
 169       Extended Tcl.
 170
 171     o experimental - An directory of expermintal and contributed Tcl source.
 172       The code is not normally built as part of TclX.
 173
 174 HOW TO BUILD IT
 175 ===============
 176
 177    Please read TclX.man in the tclX6.4c/man directory before starting the
 178 engine or working under the hood.
 179
 180     Configure and build Berkeley Tcl as described in that distribution.  Don't
 181 forget to do a "csh config" before running make for the first time.
 182
 183     Cd to the "tclX6.4c" directory, which contains this distribution.  Edit the
 184 file "Config.mk" to configure Extended Tcl for your Unix version and your
 185 preferences.  The first part of this file contains user preference options,
 186 including the location of the Berkeley Tcl source and, optionally, the Tk 2.3
 187 source.  A macro TCL_CONFIG_FILE is also defined that points to a Unix system
 188 configuration file in the "config" directory.  There should be one there for
 189 your system.  If not, you will have to develop one based on the documentation
 190 in "Config.mk".  If you develop or fix problems in a configuration file,
 191 please send it to us at the address below.
 192
 193     Now do a "make".  If all goes well, this will augment the tcl.a library
 194 will all of the functions defined by both Berkeley and Extended Tcl, and
 195 create an executable version of tcl in the "tclX6.4c" directory called, simply
 196 enough, "tcl".  A "wish" executable will be also built if it was requested.
 197
 198     Until the Extended Tcl runtime files are installed, "tcl" and "wish" can't
 199 be run directly.  To run them before installation, use "runtcl" or "runwish".
 200
 201     Next enter the command "runtcl" and, if everything worked, you should be
 202 greeted by a tcl prompt:
 203
 204 tcl>
 205
 206    Note that until Extended Tcl is installed, it will only run while in the
 207 tclX6.4c directory.
 208
 209 RUN TESTS TO INSURE THAT TCL IS WORKING PROPERLY
 210 ================================================
 211
 212     Tcl and TclX come with over 1400 tests that you can run to insure that it
 213 is working properly.  These tests have greatly helped us while working on Tcl
 214 by detecting bugs that get introduced accidentally as side-effects of changes.
 215 Consequently, we have found Tcl to be very reliable, and have had very few
 216 cases where a new release has regressed by introducing new bugs in old
 217 functions, or reintroducing old bugs in old functions.
 218
 219    There are two sets of tests: the tests from Berkeley Tcl, and tests for
 220 Extended Tcl, which test both the new commands added by Extended Tcl and the
 221 procedures defined in the Tcl procedure library.
 222
 223     Run both the Berkeley and TclX tests by typing "make test" in the Extended
 224 directory.
 225
 226     If a test fails, please dig into the test and the C source for the function
 227 being tested, fix the bug and mail us the change.  If you're not inclined to
 228 do this, please report the problem, including the output of the test, to
 229 tcl-project@neosoft.com.  Sometimes tests fail due to problems in the system
 230 environment or bugs in that test rather than problems with TclX.  Even if a few
 231 of the tests fail, you probably still have a working TclX.
 232
 233    If you're having trouble with the Berkeley tests, and you suspect that the
 234 extensions might be involved, you can build a special minimal version of
 235 Berkeley Tcl by cd'ing to the tcl6.4 directory and doing a "make tclTest".
 236 You can then invoke "tclTest", where you should be greeted by a "%" prompt.
 237 Next, cd to the tests directory and do a "source all".
 238
 239     Note that the Berkeley tests turn off tcl's ability to autoload procedures
 240 from the Tcl source library, so after running the tests, you should usually
 241 exit Tcl and restart it.
 242
 243 INSTALLING EXTENDED TCL
 244 =======================
 245
 246     To install Extended Tcl, edit the tclX6.4c/Config.mk installation
 247 configuration section to match your preferences. Read the information in the
 248 Makefile carefully before configuring it. Cd to the tclX6.4c directory and do
 249 a "make install" (normally as root).  This will install include files and
 250 manual pages for Berkeley Tcl and TclX, as well as the TclX binary and
 251 library.
 252
 253     The Tcl default file may be used to install more than one version of
 254 TclX on a system.
 255
 256 MAKING EXECUTABLE TCL SCRIPTS
 257 =============================
 258
 259     It is common to want to write Tcl scripts, put them in a directory along
 260 your search path, and execute them just like you do with shell scripts.
 261
 262 On systems that support the "#!" convention, you can put a
 263
 264 #!/usr/local/bin/tcl
 265
 266 as the first line of your script, and executing the script will
 267 automatically invoke tcl to process it.  Of course if you install
 268 Tcl somewhere else, you'll use a different path.
 269
 270     For systems that don't support this convention (most System V
 271 systems, for example), it is probably best to create a shell
 272 script that does something like:
 273
 274         exec tcl commandfile.tcl
 275
 276
 277 PACKAGE LIBRARIES
 278 =================
 279
 280     Package Libraries are a Tcl source code management tool included in
 281 this release.  Package libraries allow you to group Tcl procedures into
 282 logical bundles and create single files, libraries, that contain multiple
 283 packages.  The package code provides a low-overhead means of automatically
 284 demand-loading a package on the first attempt to execute one of the procedures
 285 defined within it.  As such, package libraries provide a mechanism to
 286 accommodate the creation of Tcl applications and libraries of a substantial
 287 size.
 288
 289 SUPPORT FOR EXTENDED TCL
 290 ========================
 291
 292     We are committed to providing continuing support for Extended Tcl.  Please
 293 send questions, bug reports, and bug fixes to:
 294
 295          tcl-project@NeoSoft.com (uupsi!sugar!tcl-project)
 296
 297 Or leave a note on our BBS at (713) 684-5900
 298
 299 SEND US YOUR LIBRARY ROUTINES
 300 =============================
 301
 302     If you write a useful Tcl procedure and would like to share it with
 303 everyone, send us a copy and we'll consider it for the Tcl library!
 304
 305 COMPATIBILITY WITH TCLX 6.2b
 306 ============================
 307
 308    We have attempted to main backwards-compatibility with older versions
 309 of TclX.  A few changes were made to enhance usability or fix problems that
 310 have introduced a few incompatibilities, these are listed below.  Remember
 311 that multiple versions of Tcl may be installed on a system using the Tcl
 312 default file.  This is useful when converting applications to the new version.
 313
 314     o The "wait" command only takes one pid.  This is in anticipation of
 315       supporting full waitpid functionallity in the wait command.  This will
 316       be available as soon as it is supported in UCB Tcl.
 317
 318     o The -i flag has been dropped from the "chmod" command.  It now assumes
 319       that the number is decimal unless prefixed by a 0.
 320
 321     o The "fcntl" command has been changed to use Posix defined flag names.
 322       NDELAY has been renamed NONBLOCK and CLEXEC is now CLOEXEC.  The command
 323       no longer returns a list of current values, instead individule values
 324       may be queried.
 325
 326     o The format of the data returned by "signal get" has changed.  Enough
 327       information is now returned to be able to reset signals.
 328
 329     o The "fstat" command has changed to make it easier to get single values,
 330       consequently the syntax to return stat data in an array has changed.
 331
 332     o A parameter has been added to the Tcl_GetKeyedListKeys C function.
 333
 334     o The format of package library index files (.tndx) has changed.  These
 335       should be purged and rebuilt.
 336
 337     o Added an options argument to Tcl_Startup.  It is not currrently used.
 338
 339
 340 CAVEATS
 341 =======
 342
 343     Although Extended Tcl compiles and executes the tests properly on SCO Unix
 344 System V/3.2.4, Xenix System V/386, and SunOS, it has not had much use under
 345 Xenix System V/386.
 346
 347 comp    Previous versions of Extended Tcl have also run under Berkeley BSD, HP-UX
 348 and Xenix/286.  This release, however, has not been tested on these machines,
 349 although there is configuration information in the makefile for BSD and HP-UX,
 350 and Extended Tcl should come up fairly easily on these machines.
 351
 352     Do not create any set-user-id versions of Tcl yet.  There are holes in
 353 the startup sequence involving shell variables and default files that need
 354 to be plugged first.
 355
 356 MAILING LISTS AND NEWSGROUPS FOR TCL
 357 ====================================
 358
 359     A Usenet newsgroup, comp.lang.tcl, is dedicated to discussing Tcl, Tk and
 360 the applications that embed it.
 361
 362 WHERE TO GET IT
 363 ===============
 364
 365 Tcl 6.4 is available via anonymous ftp from:
 366
 367    sprite.berkeley.edu:tcl/tcl6.4.tar.Z
 368 or
 369    ftp.uu.net:languages/tcl/tcl6.4.tar.Z
 370
 371 Extended Tcl 6.4c can be downloaded by anonymous FTP from:
 372
 373    sprite.berkeley.edu:tcl/tclX6.4c.tar.Z
 374 or
 375    barkley.berkeley.edu:tcl/extensions/tclX6.4c.tar.Z
 376 or
 377    ftp.uu.net:languages/tcl/tclX6.4c.tar.Z
 378
 379 A contributed sources archive resides on barkley.berkeley.edu.
 380