INTRODUCTION
============
This package contains the following files that add dynamic loading
capabilities to the Extended Tcl shell (currently for v6.2b):

	README.dynload		You're reading it...

	TclX_dld.patch		Patch file to TclX sources

	src/dynload.c		Dynamic loading support files
	src/dynload.h

	tcllib/help/dynload/*	Rudimentary Tcl help files

	examples/dynload/*	Example files

Note that you must have previously installed the GNU dld (Dynamic LoaDer)
library.  The latest version of the library is available via anonymous FTP:

	prep.ai.mit.edu:/pub/gnu/dld-3.2.3.tar.Z	[18.71.0.38]

Four Tcl built-in primitives are added to the TclX shell:

	loadbin <objfile>
		Dynamically loads <objfile> into tcl.

	unloadbin <objfile>
		Dynamically unloads <objfile> from tcl.

	bindproc <procname> <objfuncname>
		Binds <procname> to the object primitive <objfuncname>.

	unbindproc <procname>
		Unbinds the object primitive associated with <procname>.

Note that <objfile> may be either an object code (.o) or library (.a) file.
Also, <objfuncname> assumes BSD's (I think) C-style symbol name translation:
it prepends an underscore to <objfuncname>, eg.:

	bindproc foo bar

binds the symbol labeled "_bar" to the Tcl procedure "foo".  You'll have to
find out the naming conventions for other languages (I foresee big problems
with C++ 8-).

I've included example files in examples/dynload for your perusal.  The file
"dyntest" is a Tcl script that loads two object modules (test.o and
test1.o), binds procedures to Tcl names and executes them.  To run:

(1) Edit the TCL_INCLUDE_DIR variable in examples/dynload/Makefile.

(2) Run "make" in examples/dynload/.

(3) Start tcl and type "source dyntest".

INSTALLATION
============
(1) Unpack this shar file in the TclX main directory ("extended" by default).

(2) Apply the TclX source patches with the patch utility:

	patch -p0 < TclX_dld.patch

(3) Rebuild the TclX distribution in the usual way.

ADMINISTRIVIA
=============
* This package was put together in a rather hasty fashion.  I welcome all
  comments and suggestions for improvement, particularly in the area of
  documentation.  Please send them to the address listed at the end of this
  README file.

* The GNU dld library currently supports only VAXen, Sun 3s and 4s, Sequent
  Symmetries and Atari STs.  A project that's long been in my pipeline is to
  integrate dld with the GNU bfd (Binary File Descriptor) library that's
  packaged with GNU gdb.  Please email me if you're interested in tackling
  this project -- success would result in a dynamic-loading TclX shell on
  *any* architecture that supports gdb.

* Grateful acknowledgements go to:
  - John Ousterhout, for developing Tcl
  - The TclX Development Team, for (what else?) TclX
  - W. Wilson Ho, for dld.
  - Everyone who's been clamoring for dynamic loading in Tcl, for the
    inspiration 8-)

Adrian J Ho
adrianho@barkley.berkeley.edu
Jul 10, 1992