home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tclX6.5c / README.EXTD < prev    next >
Encoding:
Text File  |  1992-12-19  |  12.4 KB  |  331 lines
  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.5, 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.5.  You take the Extended Tcl package, add it to Tcl
  14. 6.5, 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 3.0 wish shell (wishx) with the
  18. Extended Tcl 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.     o Time and date manipulation and conversion commands.
  61.  
  62. ON-LINE HELP
  63. ============
  64.  
  65.     There is a help system included with Extended Tcl.  It contains some
  66. documentation on every command in Berkeley Tcl, and Extended Tcl.  You can
  67. invoke it interactively from within Extended Tcl by typing "help".
  68.  
  69.     Once you bring Tcl up and have gotten it to pass all the tests, try typing
  70. "help help" to learn how to use help.
  71.  
  72. MANUAL PAGES
  73. ============
  74.  
  75.     Man pages in nroff/troff format are provided for all of Tcl and the
  76. extensions in the directory tclX6.5c/man.  Start with the TclX.man manual.
  77.  
  78. EXTENDED TCL VERSION NAMING
  79. ===========================
  80.  
  81.     Extended Tcl takes its version number from the corresponding version of
  82. Berkeley (Ousterhout) Tcl upon which it is based, with the addition of a
  83. trailing letter in case there are multiple releases of Extended Tcl within a
  84. single release of Berkeley Tcl.  This release is TclX 6.5c.
  85.  
  86. INTERFACING TCL AND C++
  87. =======================
  88.  
  89. C++ programmers can include the file "tcl++.h" to define C++ classes
  90. that can be used to access a Tcl interpreter.  This is based on Tcl
  91. C++ classes originally developed by Parag Patel.
  92.  
  93. TCL DIRECTORY HIERARCHY
  94. =======================
  95.  
  96. Here is an overview of the directory hierarchy:
  97.  
  98.                              top_level_directory
  99.  
  100.                           tcl6.5    tclX6.5c   tk3.0
  101.  
  102. The tcl6.5 directory contains Berkeley Tcl, unmodified and tk3.0 contains
  103. unmodified tk3.0, if you plan to use Tk  These locations are only suggested,
  104. they maybe changed by editing tclX6.5c/Config.mk.
  105.  
  106. The following directories are included under the tclX6.5c directory:
  107.  
  108.     o config - Configuration files for various Unix versions.
  109.  
  110.     o man - Unformated manual pages for TclX.
  111.  
  112.     o src - The main source for TclX.
  113.  
  114.     o osSupport - Library routines required by TclX that may not be available
  115.       on all Unix versions. 
  116.  
  117.     o ucbsrc - A makefile and sed scripts used to modify source files that
  118.       are supplied with UCB Tcl.  The files are modified with sed so you don't
  119.       have to have patch to build Tcl, however context diffs are provided if
  120.       problems occur porting to a new version of Tcl.
  121.  
  122.     o tclsrc - Tcl source that is built into the Tcl package library.
  123.  
  124.     o tcllib - Tcl source and runtime environment that is required to run TclX.
  125.  
  126.     o tcllib/help - Help files for Tcl and TclX.
  127.  
  128.     o tests - Tests for TclX.
  129.  
  130.     o tkucbsrc - A makefile and sed scripts used to modify source files that
  131.       are supplied with Tk to add in TclX functionality.  Context diffs are
  132.       also provided.
  133.  
  134.     o tksrc - A makefile that builds a version of the Tk wish shell containing
  135.       Extended Tcl.
  136.  
  137.     o experimental - An directory of expermintal and contributed Tcl source.
  138.       The code is not normally built as part of TclX.
  139.  
  140. HOW TO BUILD IT
  141. ===============
  142.  
  143.    Please read TclX.man in the tclX6.5c/man directory before starting the
  144. engine or working under the hood.
  145.  
  146.     Configure and build Berkeley Tcl as described in that distribution.  Don't
  147. forget to do a "csh config" before running make for the first time.
  148.  
  149.     Cd to the "tclX6.5c" directory, which contains this distribution.  Edit the
  150. file "Config.mk" to configure Extended Tcl for your Unix version and your
  151. preferences.  The first part of this file contains user preference options,
  152. including the location of the Berkeley Tcl source and, optionally, the Tk 3.0
  153. source.  A macro TCL_CONFIG_FILE is also defined that points to a Unix system
  154. configuration file in the "config" directory.  There should be one there for
  155. your system.  If not, you will have to develop one based on the documentation
  156. in "Config.mk".  If you develop or fix problems in a configuration file,
  157. please send it to us at the address below.
  158.  
  159.     Now do a "make".  If all goes well, this will augment the tcl.a library
  160. will all of the functions defined by both Berkeley and Extended Tcl, and
  161. create an executable version of tcl in the "tclX6.5c" directory called, simply
  162. enough, "tcl".  A "wishx" executable will be also built if it was requested.
  163.  
  164.     Until the Extended Tcl runtime files are installed, "tcl" and "wishx" can't
  165. be run directly.  To run them before installation, use "runtcl" or "runwishx".
  166.  
  167.     Next enter the command "runtcl" and, if everything worked, you should be
  168. greeted by a tcl prompt:
  169.  
  170. tcl>
  171.  
  172.  
  173. RUN TESTS TO INSURE THAT TCL IS WORKING PROPERLY
  174. ================================================
  175.  
  176.     Tcl and TclX come with over 1400 tests that you can run to insure that it
  177. is working properly.  These tests have greatly helped us while working on Tcl
  178. by detecting bugs that get introduced accidentally as side-effects of changes.
  179. Consequently, we have found Tcl to be very reliable, and have had very few
  180. cases where a new release has regressed by introducing new bugs in old
  181. functions, or reintroducing old bugs in old functions.
  182.  
  183.    There are two sets of tests: the tests from Berkeley Tcl, and tests for
  184. Extended Tcl, which test both the new commands added by Extended Tcl and the
  185. procedures defined in the Tcl procedure library.
  186.  
  187.     Run both the Berkeley and TclX tests by typing "make test" in the Extended
  188. directory.
  189.  
  190.     If a test fails, please dig into the test and the C source for the function
  191. being tested, fix the bug and mail us the change.  If you're not inclined to
  192. do this, please report the problem, including the output of the test, to
  193. tcl-project@neosoft.com.  Sometimes tests fail due to problems in the system
  194. environment or bugs in that test rather than problems with TclX.  Even if a few
  195. of the tests fail, you probably still have a working TclX.
  196.  
  197.    If you're having trouble with the Berkeley tests, and you suspect that the
  198. extensions might be involved, you can build a special minimal version of
  199. Berkeley Tcl by cd'ing to the tcl6.5 directory and doing a "make tclTest".
  200. You can then invoke "tclTest", where you should be greeted by a "%" prompt.
  201. Next, cd to the tests directory and do a "source all".
  202.  
  203.     Note that the Berkeley tests turn off tcl's ability to autoload procedures
  204. from the Tcl source library, so after running the tests, you should usually
  205. exit Tcl and restart it.
  206.  
  207.     You will not be able to run the Tk demos with wishx until after Extended
  208. Tcl has been installed.  At that time, you can run the demos with a procedure
  209. "tkdemo".  This is handy for showing Tk off to you friends.
  210.  
  211. INSTALLING EXTENDED TCL
  212. =======================
  213.  
  214.     To install Extended Tcl, edit the tclX6.5c/Config.mk installation
  215. configuration section to match your preferences. Read the information in the
  216. Makefile carefully before configuring it. Cd to the tclX6.5c directory and do
  217. a "make install" (normally as root).  This will install include files and
  218. manual pages for Berkeley Tcl and TclX, as well as the TclX binary and
  219. library.
  220.  
  221.     The Tcl default file may be used to install more than one version of
  222. TclX on a system.
  223.  
  224. MAKING EXECUTABLE TCL SCRIPTS
  225. =============================
  226.  
  227.     It is common to want to write Tcl scripts, put them in a directory along
  228. your search path, and execute them just like you do with shell scripts.
  229.  
  230. On systems that support the "#!" convention, you can put a
  231.  
  232. #!/usr/local/bin/tcl
  233.  
  234. as the first line of your script, and executing the script will
  235. automatically invoke tcl to process it.  Of course if you install
  236. Tcl somewhere else, you'll use a different path.
  237.  
  238.     For systems that don't support this convention (most System V
  239. systems, for example), it is probably best to create a shell
  240. script that does something like:
  241.  
  242.         exec tcl commandfile.tcl
  243.  
  244.  
  245. PACKAGE LIBRARIES
  246. =================
  247.  
  248.     Package Libraries are a Tcl source code management tool included in
  249. this release.  Package libraries allow you to group Tcl procedures into
  250. logical bundles and create single files, libraries, that contain multiple
  251. packages.  The package code provides a low-overhead means of automatically
  252. demand-loading a package on the first attempt to execute one of the procedures
  253. defined within it.  As such, package libraries provide a mechanism to
  254. accommodate the creation of Tcl applications and libraries of a substantial
  255. size.
  256.  
  257. SUPPORT FOR EXTENDED TCL
  258. ========================
  259.  
  260.     We are committed to providing continuing support for Extended Tcl.  Please
  261. send questions, bug reports, and bug fixes to:
  262.  
  263.          tcl-project@NeoSoft.com (uupsi!sugar!tcl-project)
  264.  
  265. Or leave a note on our BBS at (713) 684-5900
  266.  
  267. SEND US YOUR LIBRARY ROUTINES
  268. =============================
  269.  
  270.     If you write a useful Tcl procedure and would like to share it with
  271. everyone, send us a copy and we'll consider it for the Tcl library!
  272.  
  273. COMPATIBILITY WITH TclX 6.4c
  274. ============================
  275.  
  276.    We have attempted to main backwards-compatibility with older versions
  277. of TclX.  A few changes were made to enhance usability or fix problems that
  278. have introduced a few incompatibilities, these are listed below.  Remember
  279. that multiple versions of Tcl may be installed on a system using the Tcl
  280. default file, so you don't have to convert everything at once.
  281.  
  282.   o Only set SIGINT to cause an error if the Tcl shell or wish is reading
  283.     commands from stdin.
  284.  
  285.   o Renamed the Extended Tcl wish shell to "wishx", so both extended and
  286.     standard versions can be installed on the system.
  287.  
  288. CAVEATS
  289. =======
  290.  
  291.     Although Extended Tcl compiles and executes the tests properly on SCO Unix
  292. System V/3.2.4, Xenix System V/386, and SunOS, it has not had much use under
  293. Xenix System V/386.
  294.  
  295.     Previous versions of Extended Tcl have also run under Berkeley BSD, HP-UX
  296. and Xenix/286.  This release, however, has not been tested on these machines,
  297. although there is configuration information in the makefile for BSD and HP-UX,
  298. and Extended Tcl should come up fairly easily on these machines.
  299.  
  300.     Do not create any set-user-id versions of Tcl yet.  There are holes in
  301. the startup sequence involving shell variables and default files that need
  302. to be plugged first.
  303.  
  304. TCL USENET NEWSGROUP
  305. ====================
  306.  
  307.     A Usenet newsgroup, comp.lang.tcl, is dedicated to discussing Tcl, Tk and
  308. the applications that embed it.
  309.  
  310. WHERE TO GET IT
  311. ===============
  312.  
  313. Tcl 6.5 is available via anonymous ftp from:
  314.  
  315.    sprite.berkeley.edu:tcl/tcl6.5.tar.Z
  316. or
  317.    ftp.uu.net:languages/tcl/tcl6.5.tar.Z
  318.  
  319. Extended Tcl 6.5c can be downloaded by anonymous FTP from:
  320.  
  321.    sprite.berkeley.edu:tcl/tclX6.5c.tar.Z
  322. or
  323.    barkley.berkeley.edu:tcl/extensions/tclX6.5c.tar.Z
  324. or
  325.    ftp.uu.net:languages/tcl/tclX6.5c.tar.Z
  326.  
  327. A contributed sources archive resides on barkley.berkeley.edu.
  328.  
  329. Remember to mail Extended Tcl problems and questions to tcl-project@NeoSoft.com
  330. not John Ousterhout.
  331.