OAT README

RCS:  $Id: README,v 1.4 1996/11/04 03:00:49 safonov Exp $

1. Introduction
---------------

This directory contains the sources and documentation for OAT, an 
extension to Tcl that provides a protocol for tracing Tcl object attributes. 
OAT extends the original Tcl variable traces (and borrows from 
their implementation). The idea behind OAT is that it may be useful
to specify Tcl or C code to be executed when a slot of an object changes.
Since there are several object systems for Tcl and Tk, OAT tries
to be generic enough to support them. An example of an "object system"
are Tk widgets. An example of creating a trace on a Tk widget attribute
may look as follows:
  oatrace widget .top -width w update_height
where restrict_width is a Tcl procedure that accepts widget name, attribute
name, operation (write) as arguments, and sets the widget ``-height'' 
attrribute to be twice the ``-width''.

OAT by itself does not create any new traceable object types. It is 
distributed with TkOAT, a sample extension to Tk which uses OAT
to enable traces on Tk widget attributes and canvas item attributes.

OAT protocol consists of two parts:
  - functions to create, query and delete traces on object attributes;
  - function and data structure to create a new traceable object type.
OAT also replaces the Tcl "trace" command with the extended "oatrace"
command that is backward compatible with "trace" for variable traces,
and can be extended to manipulate traces on new object types. OAT
should probably redefine the "trace" instead of creating a new one,
but the package mechanism in Tcl currently does not allow to redefine
existing commands in packages.

To create a new traceable object type, two things must be done.
First, a structure of type ``Oat_TraceableObjType'' must be declared,
initialized and passed to function ``Oat_CreateTraceableObjType()''.
This can be done, for example, in the package initialization function.
See tkoat.c on how this is done for the TkOAT extension. In the 
structure, 3 unique keywords must be specified. These will be used 
as subcommands of the "oatrace" command to respectively create, query, 
and delete trace operations for attributes of this traceable object type. 
For example, the built-in variable traces in Tcl use the "variable", "vinfo", 
and "vdelete" keywords. The TkOAT extension provides widget traces, 
manipulated from Tcl with the "widget", "winfo", and "wdelete" keywords, 
while canvas item traces use "citem", "cinfo", and "cdelete" to create, 
query and delete traces, respectively. See the "trace" man page for more 
information on the original Tcl trace command.

Second, calls to Oat_CallTraces() should be inserted where attribute
values for this object type can be changed (OAT currently only
supports write traces, though read and unset traces may be added in the
future). This is easy to do if object attributes are modified via
a form of Tk configure mechanism. For example, the only place where
Oat_CallTraces should be called for widget attribute updates is DoConfig()
in tkConfig.c

OAT is also distributed with TclProp v2.0b, a simple formula
propagation manager written in Tcl. TclProp was originally developed
by Sunanda Iyengar and Joseph Konstan (konstan@cs.umn.edu).

OAT is designed to be used as a dynamically loadable extension.
It does not make any changes to the Tcl source. See the Installation section 
of this file on how to create the shared library, liboat.so. 

Extensions built on top of OAT, such as TkOAT, are also supposed 
to be dynamically loaded. However, since stock Tk currently does not support
notifications when widget and canvas item attributes are changed, TkOAT
patches the Tk (but not Tcl) source. A programmer who writes his extension
for a new traceable object type, should try to make it dynamically loadable
and not requiring any changes to stock Tcl and Tk.

Brian Bailey (bailey@cs.umn.edu) has a beta version of trace support for 
CMT (Continuous Media Toolkit) objects. Contact him for more information.

2. Documentation
----------------

Look at README and TODO files for OAT and TkOAT. The header file
oat.h contains documented prototypes for externally accessible C functions
in the extension. Look at tkoat.c in the TkOAT extension, and patches to
Tk 4.1/4.2 for information on how to create new traceable object types.


3. Installation
-------------------------------

OAT works with Tcl 7.5/7.6, and Tk 4.1/4.2. It has been developed 
and tested on Unix platforms only (Linux 2.x, Solaris 2.4, SunOS 4.1,
Irix 5.3, HPUX 10.0). Makefile updates that allow OAT to compile
on Windows/Mac are welcome. 

Unarchive the OAT distribution:
  gunzip -c oat.tar.gz | tar xvf -

Directory ``oat'' will be created under the current directory, and files 
placed in it. Change to that directory, and run configure:
  ./configure --enable-shared [--with-tcl=DIR]

If you do not specify the --with-tcl argument to configure, it assumes
Tcl sources live in directory tcl7.6 at the same level as the
``oat'' directory. You can choose which version of Tcl to use, 7.5 or 7.6,
by setting the tcl_ver variable at the beginning of configure and configure.in.

Note that the OAT configure script relies on tclConfig.sh script being 
present in tcl7.x/unix directory, so Tcl should be configured prior to 
configuring OAT.

The configure script is based on the dynamic extension example put out by
SunLabs. The configure scripts also accepts the standard --enable-gcc
switch.

Run make. If you get error trying to run tclsh, make sure it is in your
path. If there are errors loading libtcl7.6.so or liboat.so, make sure 
that LD_LIBRARY_PATH (or other similar variable, e.g., LD_ELF_LIBRARY_PATH),
points to the directories containing the Tcl and newly compiled OAT
shared libraries.

If the make process completes successfully, the ``pkgIndex.tcl'' file will
be created. To load OAT into the interpreter, make sure that Tcl 
variable ``auto_path'' includes the directory with pkgIndex.tcl for OAT,
and put the command
  package require oat

in your Tcl script.


4. Summary of changes in OAT 1.0
--------------------------------

This is the first public beta-release.


5. Support and bug fixes
------------------------

Please email your system configuration (uname -a), Tcl and Tk versions,
compiler brand and version (gcc -v for gcc), suggested functionality
or bug reports to me, safonov@cs.umn.edu.

