Source Code 1992 March/Source_Code_CD-ROM_Walnut_Creek_March_1992.iso/usenet/altsrcs/2/2340

Internet Message Format | 1990-12-28 | 24.6 KB

From: [e-mail] (Karl Lehenbauer)
Newsgroups: alt.sources
Subject: Tcl - a tool command language for Unix   README
Message-ID: <[e-mail]>
Date: 18 Dec 90 08:48:08 GMT

WELCOME TO TCL
==============

Welcome to Tcl, a string processing language and programming environment
for the Unix operating system.

This is release 4.0, a beta release made to the Usenet alt.sources newsgroup
beginning on Sunday, December 16th, 1990.


WHAT TCL IS
===========

Tcl stands for "Tool command language", and was invented by Dr. John
Ousterhout and his graduate students at the University of California
at Berkeley.  (For a rationale for why Tcl was invented, a paper was
presented at the Winter '90 Usenix and is available in the proceedings
of that conference.  It is also included in machine-readable form in
this release, as the postscript file tcl/baseline/man/usenix.ps.
For those without postscript printing capability, a text file called
tcl/baseline/man/usenix.text is provided.)

Tcl is pronounced "tickle," although a lot of people (including us most of
the time) call it T-C-L.


WHAT THIS TCL IS
================

This release of Tcl builds on Ousterhout's embeddable interpreter to provide
Unix with a powerful string and file processing language that is easy
to learn, understand and write understandable programs in.

Tcl achieves its power without sacrificing elegance and simplicity by
keeping the syntax simple and implementing most operations as Tcl
subroutines.

In our experience, large scripts written in Tcl tend to run around ten to
twenty times faster than large Bourne shell scripts calling the usual
mix and density of sed, awk, grep, expr and so forth.

The Unix extensions were invented and implemented by Karl Lehenbauer
([e-mail]), Mark Diekhans (uunet.uu.net!cruzio!osprey!markd)
and Peter da Silva ([e-mail]) with help from Jordan Henderson
([e-mail]).  They consist of extensions to Tcl to support
extended string and list operations, stdio-style I/O to files and pipelines,
scanning files for regular expressions and executing Tcl code when they're
found, sorting, sorted file searching, associative arrays (arrays with
arbitrary indexes and values), fork/wait/kill/exec Unix multitasking
operations, extensions for interactive use as a shell and awk-like command-
line operation, automatic loading of tcl source based on the invocation of
tcl under an alias name (with complete Tcl access to command line arguments),
"load on first call" demand-loading of Tcl procedures from files and Tcl
source libraries, a trace capability, and more.  (Planned future extensions
are described later in this document.)


MANY UNIX SYSTEMS ARE SUPPORTED
===============================

This release of Tcl should compile and run under most Unix System V 3.2.0
and 3.2.2 systems, Xenix, HP-UX and BSD 4.3 systems.  It should be close
on a lot of others.  Care has been taken to ensure that Tcl runs properly
on the Intel 80286.

Tcl has been tested on:

    SCO Unix 3.2.2
    SCO Xenix System V
    Microsoft Xenix/286 Rev 3.5 Zap 14
    Intel/Bell Technologies Unix System V/3.2.0
    BSD 4.3 on a Vax


C PROGRAMMERS CAN USE THIS PACKAGE TO BUILD TCL INTO THEIR APPLICATIONS, TOO
============================================================================

As an embeddable interpreter, Tcl offers a powerful, plug-in-and-go
programming language that saves the programmer who needs to provide
programmability in an application from having to design and implement his
or her own.  Tcl provides a better and more complete language than most
programmers have the time or inclination to write and could reduce the
all-too-common proliferation of similar-but-incompatible embedded
programming languages.

In addition to the Tcl programming environment for Unix, this release
also provides C programmers with everything they need to embed the
Tcl programming language into an existing application or to build a new
application and include Tcl within it.  C programmers (and people programming
in languages from which they can make C-compatible calls for that matter)
can link against the tcl.a library, which this package should produce when
you get it built successfully, to include all of the baseline capabilities,
plus any of our extensions that they like, plus any application-specific
extensions they add themselves to produce a package with a significant
runtime programmability.

We have found that including Tcl into large programs provides a good
way to decouple the bulk of the application from the user interface,
allows sophisticated users to write programs to control the application,
shortens turnaround time during development, makes many debugging tasks
easier, and allows you to code tricky data processing tasks in just a
few lines of Tcl.


YOU CAN REUSE IT, GIVE IT AWAY OR SELL IT WITHOUT ROYALTIES
===========================================================

The code contained within this package is freely redistributable without
license or royalties of any kind provided the very unrestrictive copyright
terms (we're not responsible and Berkeley is not responsible for problems;
don't delete UCB's or our copyrights or otherwise pretend that you
wrote it) in the source code are met.


ON-LINE HELP
============

There is a help system included with Tcl.  It contains at least a bit of
documentation on every, or almost every, command.  You can invoke it
interactively from within Tcl by typing "help".  The help files are
extracted from the manual pages.  See the "BUILD THE HELP FILES"
section later in this file for details.


MANUAL PAGES
============

Man pages in nroff/troff format are provided for all of Tcl and the
extensions.  These are in the "man" subdirectories of the top-level
baseline, extend, and tclsh directories.  The Tcl manual is file
Tcl.man in the baseline/src directory.  Other files in that directory
document the subroutines that support interfacing to Tcl from C.
Files in the extend/man directory document the Tcl-callable extensions.
Files in the tclsh/man directory document how packages (Tcl source
libraries) work, the insides of Tcl startup, and the procedures of
Tcl source library tcl.tlib.

A couple of files were too big to ship without being split up.
These are usenix.ps and Tcl.man in the baseline/man directory.
Tcl.man is in two parts, Tcl.man1 and Tcl.man2.  Usenix.ps is
in three, in the same manner.  A Makefile is provided in the
baseline/man directory such that a "make" in that directory will
cat the files together to create the full documents.  Note that
a "make clean" or "make realclean" at the top level will delete
Tcl.man and usenix.ps, not their component files.

As mentioned previously, a Usenix paper presented by Dr. Ousterhout is
provided as a Postscript file.  It contains an overview of Tcl, the
rationale for creating a new embeddable programming language rather
than using an existing one, speculations on future uses and so forth.
This file is usenix.ps in the baseline/man directory.



BUILDING TCL
============

This release of Tcl is not shipped as the usual shar archive.  There are
a couple of files that are too big for the version of cshar we have,
and the automatic splitting of the files required manual rejoining
of them, plus cshar complained a lot about lines being too long and
trailing whitespace.  Consequently this release is shipped as a
12-part uuencoded, compressed cpio archive.

To unpack the Tcl package, collect all twelve parts.  Strip the headers
and the trailers off each part, then cat them together and uudecode
the result.  This should produce the file tcl40.cpio.Z.  Run "compress -d"
on this to produce tcl40.cpio.  Next, cd to the directory you want to
unpack tcl into, and unpack the archive with something like
    cpio -icdvmua <tcl40.cpio

The "c" specifies that character headers were used, the "d" that
subdirectories are to be created as needed, the "v" is to be verbose,
the "m" is to retain the date of last modification, the "u" is to
unconditionally restore and the "a" resets the time of last access.

    Next, type:

    Configure

The Configuration script asks various questions in order to determine
what kind of Unix you have, where you want files installed, and so
forth.  Where possible, defaults are suggested; many of the suggested
defaults just leave things wherever they were unpacked to.  On subsequent
runs of Configure without an intervening "make realclean" the answers you
gave last time are supplied as defaults.

Note that after you run Configure to change configurations, you need
to do a "make clean" and a "make" to build up a new version of Tcl
with your new configuration selections.

The questions are detailed below:

    Enter Unix (sysv3.2.0, sysv3.2.2, bsd, hpux, xenix286 or xenix386)

Give one of the answers from the list.  If you don't have one of these
you will probably have to fiddle with the source to get it to work.
Context diffs for popular Unix variants and other systems where changes
are not too substantial are solicited.

    Directory to install Tcl binary into? [/usr/local/bin]:

"make install" will cause Tcl to be installed in the specified directory.
The directory must already exist.

    Directory tcl.a library goes into? []:

The directory that the tcl.a C library, the library you would link C
applications with to get Tcl included, goes wherever you tell it to
from here.

    Directory .tcl files go into? []:

The directory you want the .tcl files and .tlib libraries installed into.
Usually something like /usr/local/lib/tcl.  The directory must already
exist before doing an install.

    Tcl default file for configuration information [/etc/default/tcl]:

If the TCLDEFAULT environment variable isn't set, Tcl reads the Tcl source
path and path of the Tcl initialization file from the Tcl default
file.  This capability allows you to create and distribute binary copies
of Tcl without hardcoding any filepaths, other than the one to the
default file.  If the TCLDEFAULT environment variable is set, it can contain
a filename or actual Tcl source code -- examine tclsh/man/startup.man
for details.

We chose /etc/default/tcl as the suggested name of the default file
for Tcl, because that's what the /etc/default directory is all about.
Unfortunately you will likely need to have superuser privileges to write
to this directory, or get the superuser to create the file for you.
If you cannot do this, specify a path to a directory where you do have
permissions to create the default file.

If you had to get the default file created for you, but the superuser
trusts you enough to let you modify it, get them to chown the
/etc/default/tcl file to you so you can change it without bugging the
superuser.)

So that you can try out Tcl without installing it, Tcl will look
in the current directory for a file named TclDefaults before checking
the normal default file.  This is also convenient so the Tcl-based
portions of installation can run from a known base.  The Configure script
creates the TclDefaults file in the directory where you unpacked Tcl.  After
you've made up Tcl, before you install, if you run it from this directory
it should find the TclDefaults file and start up from the values it
reads in it.  "make install" tries to create the actual defaults file
if it does not exist.

Note that you should use an absolute path for this file and any other
paths that Configure prompts for, or its likely the Tcl you create
will only run from one directory, if that.


    Tcl init file [TclInit.tcl]:

If you want Tcl to load a different initialization file than the standard
one, specify its name here.

    Do you want history included?

History provides a facility for editing and redoing previously entered
command lines.  To include it adds about 6K bytes to your tcl program.
History is an area that needs improvement, but it is usable as is.

    Do you want symbolic debugging included?

If you have a C symbolic debugging capability on your system, if you
answer "y" to this question Configure will try to create Tcl with
symbolic debugging included.

    Enter your C compiler and linker debug flags

If you selected symbolic debugging you are asked this question.  The
default is "-g" which seems to work on a lot of systems.

    Do you want memory debugging included?

Memory debugging enables a special memory allocator that helps to find
memory region overflows.  It is a small performance impact and should
be used when developing new C language commands for Tcl, when using
Tcl to debug a C application and/or when you select Tcl might have a
memory problem.

    Do you want memory validation enabled?

If you selected memory debugging you are asked this question.  Memory
validation goes a step beyond memory debugging and validates all memory
regions on every allocation and deallocation.  It causes a severe
performance impact and should only be used if memory corruption problems
are suspected.  It may be enabled by default or turned on with the memory
command, so you should probably only select it here when memory problems
are causing Tcl to coredump before it comes up, or you suspect corruption
is occurring during the startup sequence.

    Do you want optimization enabled?

If you want Tcl compiled with C optimization, answer "y".  If Tcl is
misbehaving in weird ways, or say it won't pass the tests, you might
want to try rebuilding it with optimization off before digging too far,
as some C optimizers generate incorrect code in certain circumstances.

    Enter your C compiler optimization flags [-O]

By default, "-O".  If you have a different choice, enter it here.
Xenix '286 users may want to use this opportunity to enter a compiler
flag to inhibit stack probes on subroutine calls.

    Do you want profiling enabled [n]

If you select profiling, tcl will be compiled with the "-p" option, which
should generate a file named mon.out when tcl exits, where you can then
run prof to find out the execution profile of Tcl.  Note that some Unixes'
profilers don't work, sometimes produce erroneous results, or have memory
model restrictions that make them unusable.

    Enter your C compiler profiling flags [-p]

If you selected profiling, you are offered the opportunity to enter
alternate profiling flags.


The first time you build Tcl, it is probably a good idea to steer a
conservative course -- select symbolic debugging (if your system supports
it), memory debugging and don't enable optimization.  After you have verified
that your build of Tcl passes all of the included tests and any other tests
and checkout that you decide to do on your own, you can then rebuild it with
optimization enabled and so forth (don't forget to rerun the tests after doing
so.)

Then do a...

    make

If all is well after the make, there should be an executable called "tcl"
in the top level directory and if you execute it from a command line with
no parameters, it should come up, greet you with a banner, and produce
a "tcl>" prompt.

    make bldhelp

...will extract the on-line help files from the included man pages.

    make install

...will install the files in the selected target directories.

    make clean

...will delete tcl, the tcl.a C library and all of the object files within
the subtree in which Tcl was extracted and built.

    make realclean

...will delete everything "make clean" deletes, plus all of the
other files that were built by Configure to begin with, such as the
extracted makefiles, extracted Tcl source code libraries and so forth.

"Make realclean" will usually render the Tcl subtree clean enough to
where you can feed all of the remaining files to one of the archiving
programs to create a release.  Look out for the occasional stray
mon.out and so forth.


INSTALLATION
============

To install the Tcl executable, source code and man pages into the directories
you specified when you ran the Configure script, do a "make install".  You
should probably look over the top-level Makefile, which is created by
Configure, to make sure everything is really going to go where you want it.


RUN TESTS TO VERIFY THAT TCL WORKS PROPERLY ON YOUR MACHINE
===========================================================

This release of Tcl comes with quite a few test files that can
be used to verify its operation.  There are tests for the baseline
code and for the extensions.

You can run the baseline tests by starting up tcl and cd'ing to the
baseline/tests and doing a "source all".  You can run the tests of
the extensions by cd'ing to extend/tests (again from within Tcl) and
doing a "source all".  Tcl can pass all the tests on our 386-based
Unix System V/3.2.0 and 3.2.2 systems, our clunky Intel '286 Xenix
systems, our HP-UX systems and our '386 Xenix systems.  When you get
it to pass all the tests on your machine, you should have at least some
confidence that a lot of Tcl is working OK.

If any tests fail, you may have to run them by hand (the tests are files
matching the pattern "*.test" in the respecting "tests" directories.
Do an "echo $errorInfo" after a run-by-hand test fails to determine
exactly which test step failed and to provide you with a start at
determining what's wrong.

If baseline tests fail and you suspect the Tcl extensions may be
responsible, you can test a minimal Tcl built upon the baseline
system only by cd'ing to baseline/test and doing a "make".  This creates
a baseline-only version of Tcl named tclTest that should be capable
of running the baseline tests.

At the top level of the command interpreter, Tcl normally tries to
execute commands it couldn't find within Tcl as a shell command.
The "source all" command of the tests turn this capability off, and
currently you have to restart Tcl to get them back on again.  Note
that if you run the tests by hand you need to turn off the execute-
missing-commands-as-a-shell-command capability.  Right now that's
easiest by doing a "source all", then hitting the kill key after it
starts, then doing a source on the test you want to run.


BUILD THE HELP FILES
====================

The on-line help files are extracted from the Tcl manual pages included in
this package.  Once you have built and tested Tcl, you need to use it to
extract the manual pages.  From your top-level Tcl directory, do a
"make bldhelp".  Make will call Tcl to the extraction.

Note that you need to have the Unix "nroff" and "col" programs present
on your machine for this to work.


TCL DIRECTORY HIERARCHY
=======================

Here is an overview of the directory hierarchy:

                                 tcl

    baseline             extend               tclsh             ossupport

src  man  tests      src  man  tests      src  man  tclsrc         src

                                                   tcl.libsrc



The subdirectories of the baseline directory contain what we call "baseline"
Tcl.  This is the minimal portable Tcl interpreter and would be used as a
porting base for people wanting to use Tcl as an embedded programming language
within one of their C applications.

The "extend" subdirectories contain our extensions to Tcl for Unix.
Many of the Tcl C-extensions in tclu/src could be useful when embedding
Tcl as well, depending upon the application.

The Tcl source code is in the tclsh/tclsrc directory.

The "ossupport" subdirectory contains implementation of Unix routines
used by other code in Tcl that may not be supported in all Unix environments.


THE TCL SHELL
=============

The Tcl shell is an application built upon Tcl and the Tcl extensions.
It is contained within subdirectories of the tclsh directory and consists
of a simple main.c and associated files.  (You can use this as a template
for your own application's Tcl startup, if you add Tcl to one of your
applications.  In main.c, the various extensions are included by calling
their associated Tcl_Initxxx routines.  You call the ones you want, then
link against the tcl.a library, and the linker should then be able to link
them into your application.)

The Tcl shell is not yet enough of a shell for you to abandon csh, ksh
or whatever your favorite shell is.  It is, however, a totally usable
environment for writing Tcl programs.  From the Tcl shell, you can type
in Tcl procedures, run any Tcl command or procedure with arguments,
display any or all procedures, trace Tcl with various trace options, and,
yes, kick off Unix programs, including other shells, optionally returning
their output as a string to Tcl, or using pipes to feed their input or
receive their output through our Tcl stdio package.

With a small amount of care, you can create your Tcl source files so
they will run standalone (i.e. run when specified from the Tcl command
line or a Tcl alias) or interactively (loaded into an interactive Tcl
environment by the "source" command).


PACKAGES
========

Packages are a Tcl source code management tool included in this release.
Packages allow you to group code into logical bundles and create single
libraries that contain multiple packages.  The package code provides a
low-overhead means of automatically demand-loading a package on the first
attempt to execute one of the procedures it defines.  Packages are
documented in more detail in tclsh/man/packages.man.


THIS RELEASE AND OUR NEAR-TERM PLANS FOR TCL
============================================

We do not think there are many bugs in this release.  We have been using
this code for work and play at our jobs and at home for several months now,
although there has been a flurry of work on Tcl the last few weeks, getting
this release together.  The tests have helped a lot.

The install procedures are rather primitive in comparison to a Configure
that would have been generated by Larry Wall's metaconfig program.  Anyone,
feel free to help out on this.

Anyway, prior to a formal release to a mainstream Usenet sources group,
we thought we'd kick it out in alt.sources and let it get a bit more
circulation.  Please send us all bug reports and, best of all, bug fixes.

Within a few weeks after everything settles down, i.e. no new bug reports,
we'll post a more formal release.


INCOMPATIBILITIES
=================

This version of Tcl was derived from, and is mostly upwardly
compatible with, Berkeley Tcl 3.3.  The following
known backward incompatibilities exist from our version:

Exec command:
    We strip final trailing newline returned, if present.
    "<<" redirects from a string rather than "<"
    "<" now redirects from a file rather than a string

Variable parsing:
    Parsing used to stop at anything other than an alphanumeric character
    of underscore for variables referenced by the $ shorthand.  Now left-
    parens are spanned too, to handle array references.  This could
    cause problems in rare cases for old Tcl programs.

Rename command:
    We treat "rename" of a nonexistent command or procedure as an error.

Error messages:
    The text of error messages have changed in a lot of cases, possibly
    breaking "catch" routines.  Note that the errorCode variable in this
    version of Tcl really helps when writing "catch" routines.

Abbreviations:
    Berkeley Tcl optionally permitted commands to be abbreviated.  We
    removed this capability because we feel it is dangerous, that
    abbreviations that you know work will suddenly start failing
    as new procedures are added to the environment.  We hope to add
    a command completion capability, to be used when Tcl is run
    interactively, in the not too distant future.


CAVEATS
=======

Although Tcl compiles and executes the tests properly on all the
aforementioned systems, it has not had much use under Xenix System
V, HP-UX or BSD 4.3.

Do not create any set-user-id versions of Tcl yet.  There are holes in
the startup sequence involving shell variables and default files that need
to be plugged first.


ERRATA
======

The recursion limit should be smaller on the 286 because I get a core
dump in stkgro prior to actually hitting the limit...

man files are not currently auto-installed to /usr/man by a "make install" --
  we haven't worked out the nuances of man pages for all the different
  unix systems

expand needs a test

If a directory occurs twice in your Tcl search path or if "." is one of
the search path entries and the current directory is also one of the
search path entries, you will get bogus warnings about Tcl having seen
duplicate function definitions once Tcl has to locate all the packages
along the path.


HELP US
=======

Please send us your input, bug lists, bug fixes and ideas.  Please send
your complaints and details of your experiences, positive or otherwise.
If you do profiling of any significant applications you write in Tcl,
we'd like to know the results -- email us the output of prof.


EPILOGUE
========

Please direct electronic mail correspondence regarding Tcl to
[e-mail], or uunet!sugar!tcl-project, or
write:

    Hackercorp
    Attention: TCL Project
    3918 Panorama
    Missouri City, TX  77459


Or drop a note on our BBS at [phone]


----------------------------------------------------------------

@(#) %M% %I% %H%

--
-- uunet!sugar!karl
-- Usenet access: [phone]