## -*-Text-*-
 # ###################################################################
 #	Cpptcl - a C++ Tcl object integration system
 # 
 #	FILE: "README"
 #					created: 8/6/96 {7:27:27 pm} 
 #				  last update: 10/12/97 {3:35:37 pm} 
 #	Author:	Vince Darley
 #	E-mail:	<darley@fas.harvard.edu>
 #	  mail:	Division of	Applied	Sciences, Harvard University
 #			Oxford Street, Cambridge MA	02138, USA
 #	   www:	<http://www.fas.harvard.edu/~darley/>
 #	
 # ###################################################################
 ##

Cpptcl Version 2.0 
===================

In order of priority, this is what Cpptcl does:

The primary purpose of Cpptcl is to allow you to write C++ classes which 
smoothly, simply and powerfully link with the Tcl language, and expose as 
much or little of their interface to Tcl as desired (member functions and 
data members).  Object creation, destruction and manipulation are all 
supported from Tcl.  Also the C++-Tcl interface uses a lot of the powerful 
features of the C++ language to make your code much more straightforward 
than if you were to use the standard Tcl C API. Building and manipulation 
of strings, lists, evaluations,...  is all possible using stream based 
operators, so you can do things like:
	
	tcl_obj t;
	t << "store this string" << my_var << " which contains a C variable value";
	tcl_obj tt(interp);
	tt << "puts {" << t << "}" << eval;

A secondary goal is to allow you to take existing C++ classes and 
automatically wrap them inside other 'Tcl-aware' C++ classes so that
it appears to the Tcl user as if your original class is integrated with 
Tcl.

A tertiary goal is to allow you to take either of the above forms of C++ in 
Tcl object functionality and wrap such an item inside an [incr Tcl] class.  
This occurs at the Tcl rather than C++ level, although needn't look any 
different to the user.

For demonstration classes and tutorial material, look in the 'Demo' 
directory.  

Technical Documentation (including some material relating to the 
demonstration classes) is online at:

<http://www.fas.harvard.edu/~darley/EvoXandCpptcl.html>

Suggestions, improvements and feedback are always welcome.

------------------------------------------------------------------------

Installation:
	
There is currently no sophisticated installation procedure.  I have no 
desire to learn about clever configure scripts and stuff like that, but if 
you wish to contribute one, I'll happily include it.

You must first download and install Tcl8.0 (or newer) from Sun microsystems 
at ftp.smli.com.  

Unix installation (or cygwin, etc on Windows):

(also see the Important Notes below):

*	edit the file 'configMake.in' to reflect the paths you use.
*	chmod u+x configure
*	./configure
*	make

That's it.

It's curretly set up for Solaris 2.5, and to build shared libraries.  After 
building as above, you'll be left with two shared libraries.  These can be 
loaded into a plain tcl interpreter via either: 'load libCpptcl.so', 'load 
libCpptclextra.so' or with the 'package require' command.  For the latter 
you must move the file 'pkgIndex.tcl' to somewhere on your tcl 'auto_path', 
or copy its contents to another file which is.

If you'd prefer static libraries, do 'make staticLibs', or switch a comment 
in the top level makefile.  If both static and shared libraries exist, I 
don't know which are linked to preferentially!

MacOS Installation:

For MacOS, un-compress the file 'Mac.sit.hqx' using stuffIt expander, and
read the instructions in there.

Prebuilt binaries are available for PPC.

Win95, WinNT installation:

Go to the 'Win' subdirectory, and open the project Cpptcl.mcp in Metrowerks 
Codewarrior (Pro 1).  If you use VC++ or Borland, things should still compile,
link and run, but I have no projects for you.

Move the .dll's which are built to (e.g.) "C:/Program Files/Tcl/lib"
You will probably need to point the path on which the system searches
for .dll's to this same location.  On Windows this is the 'path' environment
variable.

Prebuilt binaries are available.

---------------------------------------------------

General installation notes:

*	copy 'pkgIndex.tcl' (or copy its contents) to the directory
	where shared libraries are stored.
*	create a directory 'cpptcl2.0' at the same level as the tcl8.0,
	tk8.0 library directories in your hierarchy.  Move the contents
	of 'library' to that location (or alternatively, just make a link
	from 'library' to 'cpptcl2.0' in the right location).
*	make sure your 'CPPTCL_LIBRARY' environment variable is set to
	the location of the above directory (Unix only)

After doing the above, you should be able to startup wish or tclsh and
type 'package require Cpptcl' to load in the basic Cpptcl package.

There are a few useful sample scripts in the library directory.
Try this (in wish):

	package require Cpptcl
	Cpptest tobj
	cpp::editContents tobj

To test the installation, open wish/tclsh and cd to the 'Tests' directory.
Then do 'source all' to run all current tests.

===============================================================================

Important Notes:
---------------

	For documentation, see the Cpptcl and EvoX web page on:

	<http://www.fas.harvard.edu/~darley/EvoXandCpptcl.html>

	You must use 'gmake', not make.

	Currently the shared libraries are set up to link with a bunch of
	g++'s libraries (libg++, libiostream,..).  I found this necessary
	else I got undefined symbols on 'load'ing in Tcl.  But on some
	systems this will not be required.
	
	Also note I never got dynamic loading of C++ things working
	properly in Tcl on SunOS 4.1.3 (and judging by the number
	of posts on this topic to comp.lang.tcl, nor has anyone else), 
	so I switched to Solaris.

===============================================================================

Known problems (or potential problems):
---------------------------------------

*	Although designed to be multiple-interpreter friendly, I've never
actually tested Cpptcl in a situation in which many interpreters are
used.

*	Cpptcl doesn't currently implement 'scoped' objects.  I.e. if I'm
in a procedure and I create an object, that object is a new command
at the global scope and will not vanish when the procedure returns.
There is some '#ifdef'd' code which should more or less accomplish this
goal if you change a compiler flag, but it hasn't been tested much.

*	While Cpptcl can handle operator overloading (e.g. my Pltcl package
treats 'pl col <integer>' differently to 'pl col <float>'), Tcl isn't
really designed to handle that sort of thing very efficiently, so it
is probably best avoided.  An example of why there's a problem is this:
let's say I have a matrix command 'm', and I can do things like 
'm 0 0 = 5.1', 'm size', 'm max'.  Let's say I want to design an 
assignment operator '='.  If 'n' is another matrix, 'm = n' can work
just fine.  But now if I want to implement 'm = {{0 1} {2 3}}' (for
a 2 by 2 matrix), how can I check what argument is there efficiently?
If I check first if the argument is the name of a matrix, then any long
assignment list must be converted by Tcl into a string for that check.
If that fails, then it must be converted back into a list...  There
are ways to make sure this inefficiency happens at most once per 
Tcl_Obj, but even that isn't too good.  A better solution is to 
implement 'list=', 'matrix=' or something like that.

