SWIG Tcl/Tk Plugin Module

Copyright (C) 1997
Dave Beazley
March 7, 1997

Note :
------

This was first 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.x 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.  Make sure SWIG is installed and working.  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 should 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 or later 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

How to use your extension module
--------------------------------

Note : This has only been tested with version 1 of the plugin.  

1.   Copy the shared library created by SWIG into the ~/.tclplug/tcl7.7 
     directory created by the plugin.

2.   Use the following Tcl command in your scripts :

           load $tcl_library/example.so example

     By default, the plugin will only load extensions and execute scripts
     in the plugin directory so you must copy all files that you will use
     to that location.

3.   Alternatively, for debugging purposes, you can modify the first part of 
     the file ~/.tclplug/tcl7.7/safe.tcl by appending the current working
     directory to the search path.   This will look something like the
     following :

# ----- clip ----

# This is the default list of directories from which safe interpreters
# can source files. Add to this list with lappend.

set tcl_safe_source_dirs(___DEFAULT___) [list $tcl_library]
if {[info exists tk_library]} {
    lappend tcl_safe_source_dirs(___DEFAULT___) $tk_library
}
lappend tcl_safe_source_dirs(___DEFAULT___) [pwd]    # ADD THIS

# This is the default list of directories from which safe interpreters
# can open files for reading. Add to this list with lappend.

set tcl_safe_read_dirs(___DEFAULT___) [list $tcl_library]
if {[info exists tk_library]} {
    lappend tcl_safe_read_dirs(___DEFAULT___) $tk_library
}
lappend tcl_safe_read_dirs(___DEFAULT___) [pwd]      # ADD THIS

# This is the default list of directories from which safe interpreters
# can load extensions. Add to this list with lappend.

set tcl_safe_load_dirs(___DEFAULT___) [list $tcl_library]
if {[info exists tk_library]} {
    lappend tcl_safe_load_dirs(___DEFAULT___) $tk_library
}
lappend tcl_safe_load_dirs(___DEFAULT___) [pwd]     # ADD THIS

# ---- Clip ----

4.  When using the above modified version of safe.tcl, Tcl will
    be able to load extensions and scripts from the same directory
    as you started Netscape.

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 with Unix versions of the plugin
   although it may work with Windows and Mac.

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 
---------------------

**** 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!

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.



    


		

