]> git.zerfleddert.de Git - micropolis/blame - src/tclx/readme
Import Micropolis from http://www.donhopkins.com/home/micropolis/
[micropolis] / src / tclx / readme
CommitLineData
6a5fa4e0
MG
1
2 *** README.EXTD - README file for Extended Tcl ***
3
4
5EXTENDED TCL
6============
7
8 Extended Tcl (TclX), defines a set of extensions to Tcl 6.4, the Tool
9Command Language invented by Dr. John Ousterhout of the University of
10California at Berkeley. Tcl is a powerful, yet simple embeddable programming
11language. Extended Tcl is oriented towards system programming tasks, with
12many additional interfaces to the Unix operating system, It is upwardly
13compatible with Tcl 6.4. You take the Extended Tcl package, add it to Tcl
146.4, and from that you get Extended Tcl. (Berkeley Tcl is not included in
15this distribution, obtain it from sprite.berkeley.edu).
16
17 Support is also included for building a Tk wish shell with the Extended Tcl
18command 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
22early stages from Peter da Silva (peter@NeoSoft.com).
23
24 As with Berkeley Tcl, all of Extended Tcl is freely redistributable,
25including for commercial use and resale.
26
27
28FEATURES ADDED BY EXTENDED TCL
29==============================
30
31 Here is a summary of the features added by Extended Tcl. For more details
32on the commands and functionality provided by Extended Tcl, see the manual
33page 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
61NEW 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
96ON-LINE HELP
97============
98
99 There is a help system included with Extended Tcl. It contains some
100documentation on every command in Berkeley Tcl, and Extended Tcl. You can
101invoke 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
106MANUAL PAGES
107============
108
109 Man pages in nroff/troff format are provided for all of Tcl and the
110extensions in the directory tclX6.4c/man. Start with the TclX.man manual.
111
112EXTENDED TCL VERSION NAMING
113===========================
114
115 Extended Tcl takes its version number from the corresponding version of
116Berkeley (Ousterhout) Tcl upon which it is based, with the addition of a
117trailing letter in case there are multiple releases of Extended Tcl within a
118single release of Berkeley Tcl. This release is TclX 6.4c.
119
120INTERFACING TCL AND C++
121=======================
122
123C++ programmers can include the file "tcl++.h" to define C++ classes
124that can be used to access a Tcl interpreter. This is based on Tcl
125C++ classes originally developed by Parag Patel.
126
127TCL DIRECTORY HIERARCHY
128=======================
129
130Here is an overview of the directory hierarchy:
131
132 top_level_directory
133
134 tcl6.4 tclX6.4c tk2.3
135
136The tcl6.4 directory contains Berkeley Tcl, unmodified and tk2.3 contains
137unmodified tk2.3, if you plan to use Tk These locations are only suggested,
138they maybe changed by editing tclX6.4c/Config.mk.
139
140The 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
174HOW TO BUILD IT
175===============
176
177 Please read TclX.man in the tclX6.4c/man directory before starting the
178engine or working under the hood.
179
180 Configure and build Berkeley Tcl as described in that distribution. Don't
181forget 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
184file "Config.mk" to configure Extended Tcl for your Unix version and your
185preferences. The first part of this file contains user preference options,
186including the location of the Berkeley Tcl source and, optionally, the Tk 2.3
187source. A macro TCL_CONFIG_FILE is also defined that points to a Unix system
188configuration file in the "config" directory. There should be one there for
189your system. If not, you will have to develop one based on the documentation
190in "Config.mk". If you develop or fix problems in a configuration file,
191please 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
194will all of the functions defined by both Berkeley and Extended Tcl, and
195create an executable version of tcl in the "tclX6.4c" directory called, simply
196enough, "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
199be 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
202greeted by a tcl prompt:
203
204tcl>
205
206 Note that until Extended Tcl is installed, it will only run while in the
207tclX6.4c directory.
208
209RUN 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
213is working properly. These tests have greatly helped us while working on Tcl
214by detecting bugs that get introduced accidentally as side-effects of changes.
215Consequently, we have found Tcl to be very reliable, and have had very few
216cases where a new release has regressed by introducing new bugs in old
217functions, or reintroducing old bugs in old functions.
218
219 There are two sets of tests: the tests from Berkeley Tcl, and tests for
220Extended Tcl, which test both the new commands added by Extended Tcl and the
221procedures defined in the Tcl procedure library.
222
223 Run both the Berkeley and TclX tests by typing "make test" in the Extended
224directory.
225
226 If a test fails, please dig into the test and the C source for the function
227being tested, fix the bug and mail us the change. If you're not inclined to
228do this, please report the problem, including the output of the test, to
229tcl-project@neosoft.com. Sometimes tests fail due to problems in the system
230environment or bugs in that test rather than problems with TclX. Even if a few
231of 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
234extensions might be involved, you can build a special minimal version of
235Berkeley Tcl by cd'ing to the tcl6.4 directory and doing a "make tclTest".
236You can then invoke "tclTest", where you should be greeted by a "%" prompt.
237Next, 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
240from the Tcl source library, so after running the tests, you should usually
241exit Tcl and restart it.
242
243INSTALLING EXTENDED TCL
244=======================
245
246 To install Extended Tcl, edit the tclX6.4c/Config.mk installation
247configuration section to match your preferences. Read the information in the
248Makefile carefully before configuring it. Cd to the tclX6.4c directory and do
249a "make install" (normally as root). This will install include files and
250manual pages for Berkeley Tcl and TclX, as well as the TclX binary and
251library.
252
253 The Tcl default file may be used to install more than one version of
254TclX on a system.
255
256MAKING EXECUTABLE TCL SCRIPTS
257=============================
258
259 It is common to want to write Tcl scripts, put them in a directory along
260your search path, and execute them just like you do with shell scripts.
261
262On systems that support the "#!" convention, you can put a
263
264#!/usr/local/bin/tcl
265
266as the first line of your script, and executing the script will
267automatically invoke tcl to process it. Of course if you install
268Tcl somewhere else, you'll use a different path.
269
270 For systems that don't support this convention (most System V
271systems, for example), it is probably best to create a shell
272script that does something like:
273
274 exec tcl commandfile.tcl
275
276
277PACKAGE LIBRARIES
278=================
279
280 Package Libraries are a Tcl source code management tool included in
281this release. Package libraries allow you to group Tcl procedures into
282logical bundles and create single files, libraries, that contain multiple
283packages. The package code provides a low-overhead means of automatically
284demand-loading a package on the first attempt to execute one of the procedures
285defined within it. As such, package libraries provide a mechanism to
286accommodate the creation of Tcl applications and libraries of a substantial
287size.
288
289SUPPORT FOR EXTENDED TCL
290========================
291
292 We are committed to providing continuing support for Extended Tcl. Please
293send questions, bug reports, and bug fixes to:
294
295 tcl-project@NeoSoft.com (uupsi!sugar!tcl-project)
296
297Or leave a note on our BBS at (713) 684-5900
298
299SEND US YOUR LIBRARY ROUTINES
300=============================
301
302 If you write a useful Tcl procedure and would like to share it with
303everyone, send us a copy and we'll consider it for the Tcl library!
304
305COMPATIBILITY WITH TCLX 6.2b
306============================
307
308 We have attempted to main backwards-compatibility with older versions
309of TclX. A few changes were made to enhance usability or fix problems that
310have introduced a few incompatibilities, these are listed below. Remember
311that multiple versions of Tcl may be installed on a system using the Tcl
312default 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
340CAVEATS
341=======
342
343 Although Extended Tcl compiles and executes the tests properly on SCO Unix
344System V/3.2.4, Xenix System V/386, and SunOS, it has not had much use under
345Xenix System V/386.
346
347comp Previous versions of Extended Tcl have also run under Berkeley BSD, HP-UX
348and Xenix/286. This release, however, has not been tested on these machines,
349although there is configuration information in the makefile for BSD and HP-UX,
350and 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
353the startup sequence involving shell variables and default files that need
354to be plugged first.
355
356MAILING LISTS AND NEWSGROUPS FOR TCL
357====================================
358
359 A Usenet newsgroup, comp.lang.tcl, is dedicated to discussing Tcl, Tk and
360the applications that embed it.
361
362WHERE TO GET IT
363===============
364
365Tcl 6.4 is available via anonymous ftp from:
366
367 sprite.berkeley.edu:tcl/tcl6.4.tar.Z
368or
369 ftp.uu.net:languages/tcl/tcl6.4.tar.Z
370
371Extended Tcl 6.4c can be downloaded by anonymous FTP from:
372
373 sprite.berkeley.edu:tcl/tclX6.4c.tar.Z
374or
375 barkley.berkeley.edu:tcl/extensions/tclX6.4c.tar.Z
376or
377 ftp.uu.net:languages/tcl/tclX6.4c.tar.Z
378
379A contributed sources archive resides on barkley.berkeley.edu.
380
Impressum, Datenschutz