Tcl Distributed Programming (Tcl-DP)
                 (Version 1.0a; March 11, 1993)

          Lawrence A. Rowe, Brian Smith, and Steve Yen
                Computer Science Division-EECS
              University of California at Berkeley

This directory contains a freely distributable extension to Tcl/Tk
called Tcl Distributed Programming (Tcl-DP).  Tcl-DP adds TCP and
IP connection management, remote procedure call (RPC), and
distributed object protocols to Tcl/Tk.

BACKGROUND

A C interface to the RPC primitives is also provided.  Unlike the 
"send" command of Tk, Tcl-DP does not require that Tcl/Tk processes 
that want to communicate must share an X server because Tcl-DP is 
built upon TCP/IP.

Tcl stands for the Tool Command Language, a freely distributable,
embeddable scripting language package.  Tk is an freely
distributable X windows interface toolkit and widget library
implemented by a collection of new commands added to Tcl.
Information about Tcl/Tk is available by anonymous ftp from
sprite.berkeley.edu [128.32.150.27].  Tcl-DP was developed for
Tcl 6.5 and Tk 3.0.

This distribution contains the source code for Tcl-DP, man pages
that describe the commands, and several examples that illustrate
how to use Tcl-DP to build simple distributed applications.
Tcl-DP is available by anonymous ftp from toe.berkeley.edu
[128.32.149.117].

The Makefile creates two libraries, named libtnetwork.a and libtutil.a,
that can be linked with your application programs.  The library
libtnetwork.a contains the Tcl-DP extension, and the library
libtutil.a contains basic utilities upon which Tcl-DP depends.
To use Tcl-DP, you must initialize your Tcl interpreters with the
dpInit C procedure (see network.h, and the example in main.c).
After initialization, all distributed programming can be done 
with Tcl commands.

Tcl/Tk supports on-demand autoloading of Tcl/Tk procedures.  Tcl-DP 
adds several autoloading Tcl/Tk procedures.  They are located in the 
library subdirectory.  These Tcl/Tk scripts must be copied to the 
directory that contains your existing autoloading Tcl/Tk scripts, 
and they must be listed in the tclIndex file in that directory.

In the examples subdirectory, several sample applications are supplied
that use Tcl-DP.  As you can see from the examples, the distributed 
programming mechanisms of Tcl-DP are very simple.  An RPC command, 
for example, sends a Tcl command to a remote process, which evaluates 
the command in the destination Tcl interpreter and returns the result 
as the value of the RPC command.

A dpwish program (i.e., a wish with Tcl-DP extensions) is also supplied.  
To exit dpwish, you should use the "exit" command, not the break or 
interrupt keys (i.e., Ctrl-C, Ctrl-D) as this allows Tcl-DP to clean 
up dangling network connections.  A solution to the graceful shutdown 
problem that we use in our Tcl-DP applications is to catch the 
break/kill/interrupt UNIX signals and eval the "exit" command before 
halting the application.

COMPILING/USING TCL-DP

To compile the dpwish program:

+) If you do not already have Tcl 6.5 and Tk 3.0, get a copy and follow 
the instructions to build the system.  Tcl-DP does not work with earlier 
versions of Tcl/Tk.  

+) In the Tcl-DP directory (i.e., where this README resides), follow
the configuration instructions at the start of the Makefile.  For
example, you will need to edit the Makefile variables TCL_INC,
TCL_LIB, ....

+) To make the dpwish program, type...

    make dpwish

This will make the libraries libtnetwork.a and libtutil.a and the 
dpwish program.  If you only need the libtnetwork.a and the
libtutil.a libraries, you can type...

    make libtnetwork.a
    make libtutil.a

To install the autoloading Tcl/Tk scripts of Tcl-DP:

+) Copy all Tcl/Tk scripts from the Tcl-DP/library directory to the
directory where Tcl/Tk stores your existing autoloading Tcl/Tk
scripts.  The environment variable TCL_LIBRARY (and the Tcl 6.5
Makefile) should specify where this directory is located.

+) Update the tclIndex file in that TCL_LIBRARY directory to
reflect the Tcl/Tk scripts that you copied in the last step.  You
can do this manually, or you can have Tcl/Tk automatically update
the tclIndex file with its "auto_mkindex" command.

To learn how to use Tcl-DP:

+) Read the README file in the examples subdirectory and play with
the example applications.

+) Read the Tcl-DP man page (Tcl-DP.l), and the other man pages 
in the man subdirectories.

To report bugs, bug fixes, descriptions of interesting Tcl-DP 
applications, and suggested improvements:

+) Send email to tcl-dp@roger-rabbit.CS.Berkeley.EDU or
tcl-dp-bugs@roger-rabbit.CS.Berkeley.EDU

or

+) Post an article in the comp.lang.tcl newsgroup.

We extend our thanks to everyone who helped to create, debug, and
distribute this software, including the following people:

  John Ousterhout, creator of Tcl/Tk; 
  Pekka Nikander, creator of tcpConnect;
  Tim MacKenzie, creator of tclRawTCP;