Return to readme CVS log

Up to [Micropolis - Activity] / micropolis / src / tclx

Annotation of micropolis/src/tclx/readme, revision 1.1

1.1     ! root        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: ([email protected]) and Mark Diekhans ([email protected]), with help in the
        !            22: early stages from Peter da Silva ([email protected]).
        !            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: [email protected].  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:          [email protected] (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: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.