SWIG Tcl/Tk Plugin Module

Copyright (C) 1996
Dave Beazley
August 1, 1996

Note :
------

This was released as a separate module to SWIG 1.0b3.   It is now
included in the standard SWIG Tcl module.  Just do the following :

	swig -tcl -plugin interface.i


DISCLAIMER :
------------

This is a *SUPER* experimental module.  USE AT YOUR OWN RISK!!!!!

IN NO EVENT SHALL THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, THE 
UNIVERSITY OF UTAH OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, AND THE UNIVERSITY OF UTAH
SPECIFICALLY DISCLAIM ANY WARRANTIES,INCLUDING, BUT NOT LIMITED TO, 
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND 
THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Introduction :
--------------
This example shows you how to build C extensions for the Tcl/Tk Netscape
plugin.  In other words, you can install your own C code into Netscape
and build cool applications. In order to use this package, you will
need to have SWIG1.0 already installed on your machine.

SWIG can be retrieved at :

	ftp://ftp.cs.utah.edu/pub/beazley/SWIG

More information is also available at :

	http://www.cs.utah.edu/~beazley/SWIG

Installation :
--------------

0.  First, you need to get Netscape Navigator 3.0.  
  
1.  Next, you need to get the netscape plugin from Sun. Go
    to http://www.sun.com for more information.  Follow it's
    installation instructions precisely!

2.  Copy the file 'safe.tcl' into the tcl7.6 directory of the Tcl
    plugin.   This will look something like this :

	cp safe.tcl ~/.tclplug/tcl7.6

    *** WARNING *** SWIG relaxes the Tcl/Tk plugin's security
    policy somewhat.  You may want to make a backup of 'safe.tcl'
    before doing this.  See the security notice below.	

3.  Two simple examples are provided in the directories "simple"
    and "graph".    Go into those directories in order to play 
    with them.  In order to use the examples, you you be able to
    just type "make".   The makefiles rely on "Makefile.template"
    in the top level SWIG directory so you may need to modify that
    if this should fail.    As far as I know, this example only
    works if you have tcl7.5 and tk4.1 installed on your machine.

How to build an extension for the plugin
----------------------------------------

SWIG uses the same process as used for building a Tcl7.5 dynamic
loadable module.  However, there are a number of key differences :

1.   SWIG creates an initialization function called 
     Module_SafeInit() which is needed by the safe interpreter
     used in the plugin.

2.   You must define a symbol SAFE_SWIG in your SWIG interface
     files in order for them to work.    For example :

	%module example
        %{
	#define SAFE_SWIG
	%}

	...
  
     Primarily this is a reminder that you are, in fact, adding
     C functions to a Safe Tcl interpreter.
	   
3.   Be sure to include the Tcl7.5 header files.

4.   When building the module, make sure you link with
     the netscape plugin module as follows (for Solaris):

     ld -G example.o $(HOME)/.netscape/plugins/libtclplugin.so -o example.so

Uses for a SWIG generated plugin
--------------------------------
SWIG allows you to extend the Tcl/Tk plugin with C functions.  One
possible use for this is to offload computationally intensive
operations onto a client machine including access to C libraries,
databases, and other applications from within a HTML document.  This
is probably more useful for creating specialized applications that you
might want to perform on a local or internal network. 

Known Problems and Limitations
------------------------------
1. This module is only known to work under Solaris at the moment.

2. C extensions shouldn't make output to stdout or rely on stdin.

3. There are potential incompatibilities between some functions
   defined in the Tcl7.5 header file and those used in the Netscape
   plugin.   Don't expect everything to work.

SPECIAL SECURITY NOTE 
---------------------

The file safe.tcl (provided) has been modified to allow you to
load C extensions, source Tcl scripts, and read files from the
current directory (wherever you started Netscape).     Primarily,
this is so you can play around with the plugin.

**** CAUTION ****

SWIG allows you to wrap almost any C function into a module.   Therefore,
if you do something like wrap the "exec" function or other low-level
system operation, you are asking for trouble.   Don't say I didn't warn
you!!!!!

SWIG generated extensions to the plugin will only work if they are on
a local machine and in the same directory as where you started
Netscape.  They are not transmitted as part of a Netscape document and
pose no risk to other users.  In order for others to use a SWIG
extension, a user must explicitly download it first. However, just as
you shouldn't accept candy from strangers, do not accept C extensions to
the plugin from people you don't know!

*****************************
***** SECURITY ADVISORY *****
*****************************

SWIG makes it possible to directly access C functions from HTML documents.
You should follow these rules :

1.  DO NOT DOWNLOAD ANY FOREIGN SWIG EXTENSIONS TO YOUR OWN MACHINE.  SUCH
    EXTENSIONS CAN DESTROY ALL OF YOUR FILES, CRASH YOUR MACHINE, SIPHON
    OFF PERSONAL INFORMATION, OR WORSE.   

2.  YOUR MODULE IS ONLY AS SAFE AS YOU MAKE IT!  IF YOU WRAP I/O OR SYSTEM
    LIBRARIES, YOU ARE ASKING FOR TROUBLE.

3.  DISABLE THE SWIG EXTENSION WHEN ACCESSING UNTRUSTED LOCATIONS 
    USING THE TCL/TK PLUGIN.

4.  THIS SOFTWARE IS PRIMARILY DESIGNED FOR RESEARCH APPLICATIONS AND  
    COMES "AS IS".

UNDER NO CIRCUMSTANCES, WILL THE AUTHOR, THE UNIVERSITY OF UTAH, THE
UNIVERSITY OF CALIFORNIA, OR SUN MICROSYSTEMS BE HELD LIABLE FOR DAMAGES
ARRISING FROM THE USE OF THIS SOFTWARE.

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

Ahem, with that little legal matter out of the way, have fun.



    


		

