************************************************************************
tcl2array package - toolkit to help create stand-alone tk/tcl applications
V1.02
 
Copyright (c) 1993, 1994, 1995 University of Southern California.
All rights reserved.                                            
                                                                
Redistribution and use in source and binary forms are permitted
provided that the above copyright notice and this paragraph are
duplicated in all such forms and that any documentation, advertising
materials, and other materials related to such distribution and use
acknowledge that the software was developed by the University of
Southern California, Information Sciences Institute.  The name of the
University may not be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

J. Touch / touch@isi.edu
11/18/93
************************************************************************

Tcl2array is a package developed at the University of Southern
California Information Sciences Institute, to help in the creation of
stand-alone tk/tcl applications. Tcl2array is distributed as a
compressed tar archive available via anonymous login from
ftp.isi.edu:pub/hpcc-papers/touch/tcl2array.tar.Z (128.9.0.32).  This
README is in tcl2array.README and in the tar file as well.

For version history information, see the end of this file.

Tk/tcl was developed by John Ousterhout, at Univ. of California
Berkeley, as a toolkit for the development of applications.  Tcl is a
command language interpreter, and Tk is a toolkit for graphical user
interface design in tcl for X11 systems. More information on Tk/tcl is
available on sprite.berkeley.edu (128.32.150.27).

As distributed, tk/tcl is designed to be used as an installed toolkit,
both for application development and application use. Users are
expected to install the toolkit, either in their home directory or in
a central shared directory. Applications developed in tk/tcl aren't
stand-alone; they depend on dynamically-loaded auxilliary tcl files.
Also, tk/tcl code is usually maintained as a separate file, rather
than being integrated into the executable code main.

We prefer to be able to distribute our code fully stand-alone, where a
single executable code file contains the tk/tcl source as an embedded
data structure, and also contains all auxilliary files. This way, our
executables can be used where tk/tcl has not been installed.  Here we
provide an skeleton application, and a makefile and preprocessor for
making embedded tk/tcl stand-alone applications.

At this time, tcl2array has been ported and tested on the following
systems, for tcl 3.0 and tk 3.3 (although it should work anywhere
any such equivalent or later version of tk/tcl works):
	Sun SPARC 4
	HP 700
	SGI IRIX

Tcl2array consists of:

	tcl2array.c	an application for converting tk/tcl code into
			data to embed in C source

	embed_tcl.c/.h	routines for converting the embedded data
			tk/tcl into a format usable by tk/tcl's
			interpreter

	embed_test.c	a sample skeleton main program

	TCLFILE.tcl	a sample skeleton tk/tcl program

	Makefile	a Makefile that gathers the proper tk/tcl
			files and shows processing and embedding order

	README		This file

History: 

Tcl2array was derived from Ron Frederic's (from Xerox PARC) tcl2c
program, as distributed with nv. Tcl2c turns an entire tk/tcl program
into a single C data string. Unfortunately, some compilers aren't
happy with a single data string that consists of over 4 Kbytes (our
source for mmcc's tk/tcl is about 60 Kbytes). C compilers choke on the
size of the tring because they attempt to handle the string data as a
single compiler token (which is a flaw in the compiler, we think!). As
a result, Ron partitioned nv's tk/tcl code into several small parts.
This is cumbersome, and could not be performed with our mmcc tk/tcl
program, because some of our functions were over 4 Kbytes themselves.

We instead developed tcl2array, which converts each line of tk/tcl
code into a single array element, and embed_tcl, that converts this
array structure back into a single string, suitable to pass back to
the tk/tcl interpreter.

Use:

Replace TCLFILE.tcl with your favorite tk/tcl program. Replace
embed_test.c with your favorite main program, or just use embed_test.c
as a simple main. Edit the Makefile to denote the location of your:
	tk/tcl include files
	tk/tcl libraries
	tk/tcl ".tcl" files (i.e., the value of TK_LIBRARY, if tk/tcl is installed)
	X11 includes
	X11 libraries

On some systems, notably Sun computers, some C compiler options need
to be set to make truly stand-alone code. These include the C compiler
option to indicate 'static library loading', to bundle the libraries
with the user code at compile time.  Also, add the load library
include -lresolv if you have it, otherwise DISPLAY addresses won't be
translated from names to numbers.
	
How it works:
	tcl2array NAME < tclfile.tcl > cfile.c

This creates cfile.c, which contains the declaration of a constant array of
char pointers and two long integers indicating the number of lines
(array entries) and characters (integrated over the array). The names
of the array is NAME, the names of the line and character counts are
NAME_lines and NAME_chars, respectively.

Compile cfile.c as a separate file, and add the following external
declarations to your code:
	extern char *NAME[];
	extern long NAME_lines, NAME_chars;
or simply append cfile.c to your main code. In your main file, when
you want to execute that tk/tcl file, convert it to a single string,
pass it to the interpreter, and free it:
	char *src;
	src = embed_arraytostring(NAME,NAME_lines,NAME_chars);
	result = Tcl_Eval(interp,src);
	free(src);

The routine embed_arraytostring takes three arguments:
	NAME:	null-terminated array of null-terminated strings
	NAME_lines: number of strings in the array
	NAME_chars: number of chars, summed over the strings of the array
 
Embed_arraytostring returns a pointer to a malloc'd string, long
enough to hold the entire program.

Acknowledgements:

This system was developed at USC/ISI, for the 'mmcc' teleconferencing
project. As mentioned, it is based on tcl2c of Ron Frederick at Xerox
PARC, and was developed with the assistance of Steve Casner and Eve
Schooler of the teleconferencing group at ISI.

Joe Touch
Computer Scientist 
USC/Information Sciences Institute
touch@isi.edu

************************************************************************

VERSION HISTORY

1.0	Nov 1993 	Initial release.

1.01	July 1994	Minor fix to tcl2array.c output routine to 
			avoid replicating the last line of the TCL file.

1.02	April 1995	Changed library include order to -ltk -ltcl,
			augmented the list of .tcl files included
			(this should be automatic, based on a "use"
			 dependency tree)
			Changed TCLTEST.tcl to avoid the 
			"focus default ." line that's not needed.
		
************************************************************************




