
              Tcl Distributed Programming (Tcl-DP)
                 (Version 2.0; October 1, 1993)

    Lawrence A. Rowe, Brian Smith, Stephen Tu, 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 originally developed for Tcl 6.5 and Tk 3.0.  Tcl-DP Version
2.0 is compatible with Tcl 7.0 and Tk 3.3.

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] in the /pub/multimedia/Tcp-DP directory.

The Makefile creates two libraries, named libdpnetwork.a and libdputil.a,
that can be linked with your application programs.  The library
libdpnetwork.a contains the Tcl-DP extension, and the library
libdputil.a contains basic utilities upon which Tcl-DP depends.
To use Tcl-DP, you must initialize your Tcl interpreters with the
Tdp_Init C procedure (see dpnetwork.h, tkAppInit.c and the example
in tkmain.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.

The services subdirectory contains an extended example of Tcl-DP.
It contains Tcl-DP scripts to implement a name server, a daemon to which 
server applications can advertise their location, and from which client 
applications can locate the servers.  See services/README.

A dpwish program (i.e., a wish with Tcl-DP extensions) is also supplied.  
To exit dpwish, you should use the "dp_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 "dp_exit" command before 
halting the application.

COMPILING/USING TCL-DP

To compile the dpwish program:

+) If you do not already have Tcl 7.0 and Tk 3.3, get a copy and follow
the instructions to build the system.  Tcl-DP 2.0 does not work with
earlier versions of Tcl/Tk.  Although not required, we recommend that
you place tcl-dp2.0 in a sibling directory to tcl7.0 and tk3.3, and then
make a symlink from tcl-dp2.0 to tcl-dp.

+) 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

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

    make libdpnetwork.a
    make libdputil.a

+) To install dpwish, type ...

    make install

This will install dpwish, the libraries (libdpnetwork.a and
libdputil.a), the include files, the man pages, and the autoload
scripts.

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;
  Lou Salkind, contributor of port to Tcl 7.0/Tk 3.3
  Craig Federighi, author of extended name server code
