SWIG (Simplified Wrapper and Interface Generator)
Version 1.1 Beta 5 (patch 1)

Copyright (C) 1995-1997
University of Utah and the Regents of the University of California

March 16, 1997

*** DISCLAIMER :

This is beta release software.    There are still a few glitches that
need to be worked out and I'm in the process of updating the documentation.
See the file 'NEW' for recent additions.

Note : Full documentation is not yet distributed with this release.   SWIG
documentation (for version 1.0) can be obtained at

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

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

SWIG is a compiler that makes it easy to integrate C and C++ code with
scripting languages including Perl, Tcl, and Python.  In a nutshell,
you specify a bunch of ANSI C/C++ declarations and it generates an
interface to your favorite scripting language.

SWIG is almost entirely the product of users who have used the system
and suggested new idea.  Without this support, SWIG would be not be
nearly as fun to use as it is now. Many thanks!

2.   Currently Supported Languages
----------------------------------

To use SWIG, you will need at least one of the following scripting
languages :

        Tcl7.3, Tk3.6  (and all newer versions)
	Tcl8.0, Tk8.0  (Highly experimental)
        Python1.3 (or newer)
        Perl5
	Perl4
	Guile
        [incr Tcl]

If you don't have any of these, SWIG will still compile, but it won't
be particularly useful.  Note : it is not necessary to have all of
these languages installed to use SWIG (although obviously its full
power will not be realized otherwise).

3.   Installation (Unix)
------------------------

To compile and use SWIG, you will need the following on your machine:

        A C++ compiler  (ie. g++)
        An ANSI C compiler (ie. gcc)
        yacc or bison (if you are going to rebuild the parser)

To compile and install SWIG, type the following :

        ./configure
        make
        make install

The configuration script will attempt to locate various packages on
your machine, including Tcl, Perl5, and Python.   Don't panic if
you get 'not found' messages--SWIG does not need these packages
to compile or run.   The configure script is actually looking for 
these packages so that you can try out the SWIG examples contained
in the 'Examples' directory.  See the Examples section below for
more details. 

If you are paranoid, you can type 'make test' to run a series of tests
before running 'make install'.

There are a number of configuration options that you can give to
'configure' :

        --prefix=/usr/local     

          Set the installation prefix.  SWIG installs into
          /usr/local by default.

        --exec_prefix=/usr/local

          Set the prefix used to install platform specific
          files (binaries and libraries).  Use this if the
          location is different than that given with --prefix.

        --with-lang={TCL,TCL8,PYTHON,PERL5,PERL4,GUILE}

          This lets you choose the default SWIG target language.
          By default, SWIG chooses TCL, but you can select
          another as shown :

                ./configure --with-lang=PYTHON

        --with-doc={ASCII,LATEX,HTML,NODOC}

          This lets you choose the default SWIG documentation
          method.  By default, SWIG chooses ASCII.


4.   Site specific installation
-------------------------------

While not required for compiling SWIG, the configuration script looks
for various packages in order to create a makefile for compiling the
examples.  This makefile is also installed with the SWIG package.
The following configuration options can be used to set the location
of various packages.

--with-tcl=pathname          - Set root directory of Tcl installation.
                               SWIG will use $pathname/include and
                               $pathname/lib.

--with-tclincl=pathname      - Set exact location of Tcl include files

--with-tcllib=pathname       - Set exact location of Tcl library files

--with-itcl=pathname         - Same as above but for [incr Tcl]

--with-itclincl=pathname     - Location of [incr Tcl] include files

--with-itcllib=pathname      - Location of [incr Tcl] libraries

--with-py=pathname           - Set package location of Python. This is usually
                               something like /usr/local.  configure will attempt
                               to locate the appropriate include and library files.

--with-pyincl=pathname       - Set location of Python include files 
                               (for example, /usr/local/include)

--with-pylib=pathname        - Set location of Python library files
                               (for example, /usr/local/lib)

--with-perl5=executable      - Specify your perl5 executable.  SWIG will figure
                               out where files are by running this version of 
                               Perl and grabbing its configuration data.


Other options :

--without-yacc               - Try to compile SWIG using a pregenerated YACC
                               file generated by Berkeley YACC (byacc). Only recommended
                               if you get compiler errors when trying to compile parser.y
                               or parser.cxx.

Changing the C++ compiler:

By default, SWIG will look for g++.  You can change the C++ compile as follows :

        env CXX=CC configure --prefix=/usr/local ... etc...

   or

        setenv CXX=CC
        ./configure ... etc ...

SWIG has been successfully compiled and tested under g++, the SGI C++
compiler, and the Sun C++ compiler.  

5.  Testing
-----------
The SWIG parser and language modules can be tested by typing 'make test'.
Be forewarned, this runs a huge battery of tests on all of SWIG's
language modules and documentation methods.  The tests may take 5-10
minutes to run, but a report of errors will be written to 'test.log'.
If this exists, it will contain error messages for failed tests. If
the file is missing, it means all tests were successful.

The testing process requires approximately 20-30 Mbytes of disk space.
After testing, you may wish to type 'make testclean' which will
return the testing directory to its original state.


6. Installation for Windows 95 and NT
-------------------------------------

The Win directory contains makefiles for Microsoft Visual C++ 4.x.
See the README file in the Win directory for specific build
instructions.  Many thanks to Kevin Butler (butler@cs.byu.edu)
for supplying these Makefiles.

7. Installation for Macintosh
-----------------------------

The Mac directory contains information about building SWIG on
the Macintosh.  A project file for Metrowerks Code Warrior 10
is included in bin-hex format.    The Macintosh version of
SWIG is *highly* experimental and has not been fully tested yet.


8.  Examples
------------

The 'Examples' directory contains examples for all of the supported
scripting languages. All of the examples rely on the file
'Makefile.template' located in the top-level directory.  This makefile
is created by 'configure', but the configuration process is not
foolproof.  To check this Makefile type

      make testbuild

This will attempt to build various kinds of extensions and report its
success or failure.  If this fails, you may need to edit the file
'Makefile.template' by hand.  This usually isn't difficult--just
follow the instructions contained within the file.  Once the 'make
testbuild' works for the language you are interested in using, you
should be able to build the examples.

The examples will not compile properly if you have not installed SWIG.
If you would like to try the examples before installation, set the
SWIG_LIB environment variable as follows :

      setenv SWIG_LIB ${pathname}/SWIG1.1b5/swig_lib

Where ${pathname} the location of the SWIG source.

*** NOTE *** If you are replacing an older version of SWIG with a new
one, the examples will not compile correctly unless you set the
above environment variable or do a 'make install' first.

9.   Resources
--------------

Up-to-date SWIG related information can be found at

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

SWIG source code and software updates are also available via anonymous
ftp at

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


You can join the SWIG mailing list by sending a message containing the
line "subscribe swig" to

        Majordomo@cs.utah.edu.

The SWIG mailing list is a forum for discussing various applications
of SWIG, installation problems, ideas for system improvements and
future work.

10.  Installation Problems
-------------------------

I have tested the installation on the following platforms :

        - SunOS 4.1.3
        - Solaris
        - Irix 5.3
        - Irix 6.1
        - HPUX
        - AIX 4.1
        - Linux
        - MkLinux
        - MachTen
        - UNICOS
        - Windows 95
        - MacOS System 7.5.3

SWIG development has primarily taken place on Linux, Solaris 2.5,
Irix 5.3, and MkLinux.  I've tested most of the examples on these
platforms.   I have also tested SWIG under Win95 and MacOS, but
this is still somewhat experimental.

If you've tried everything and can't get SWIG to compile, please send
me e-mail at beazley@cs.utah.edu, and we'll try to figure it out.  I
answer all e-mail that I receive.  However, occasionally I receive
messages with bad return addresses and can't respond.  If you don't
hear back from me within a few days, try sending a message to
'swig@cs.utah.edu' or posting a message on comp.lang.tcl,
comp.lang.python, or comp.lang.perl.

11.  Documentation
-----------------

Note : documentation for SWIG 1.1 is incomplete, but will be completed
by the time 1.1 final goes out the door. 

A postscript version of the user manual is in the Doc directory. At last
count, the user manual was getting rather large (over 100 pages), but
don't let this scare you.  SWIG is easy enough to use that you can
probably start using it by only looking at a simple example. However,
at some point you will probably want to know more so I hope that the
manual will come in useful.   Besides, I hate black boxes...

If you would prefer to save the life of a small tree, the manual is
also available as an Adobe PDF file and in HTML. Both are available at

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

(All three versions of the documentation are generated from the same
source and are identical in content.) 

12.  Incompatibilities
---------------------

This release should be mostly compatible with SWIG 1.0
(Final). However, the SWIG documentation system has been completely
rewritten and the C API has been changed greatly.  It is unlikely that
any custom SWIG language modules written in C++ for 1.0 will work with
1.1.  While porting to 1.1 is not that difficult, there are a number
of important changes.  See the file 'Doc/Porting' for a list of
changes to the C++ API and how to convert an older SWIG module to work
with 1.1.

13.  Bug Reports
----------------
Bug reports should be submitted to beazley@cs.utah.edu.  I am
committed to providing a quality package and will make every attempt
to fix bugs as soon as possible.  However, I can only fix bugs if I
know about them.

14.  Legal Stuff
---------------
SWIG is completely free.  You can do whatever you want with it
(including distribution), provided that you follow these rules, 1)
Keep all of the copyright notices intact, 2) don't claim that you
wrote it, and 3) Don't sue anyone if it breaks.  Otherwise, have fun.

15.  Disclaimer
----------------

While I believe that SWIG is reasonably stable, I'm always tinkering
with it and trying to make it better.  There may be a few bugs hiding
around so if you experience any problems let me know.  If you think
that SWIG is missing some capability that would be really cool to
have, post a message on the SWIG mailing list.  Most of the previous
suggestions have already been incorporated into this release.

16.  Acknowledgements
---------------------

SWIG would not be possible without the contributions of people who
tried out the beta versions and offered feedback and bug reports.
While there are far too many people to list at point, I'd like to
especially acknowledge the following individuals and organizations
for supporting SWIG and making major contributions :

David Ascher, Erik Bierwagen, Kurtis Bleeker, John Buckman, Kevin
Butler, David Fletcher, Mark Harrison, Brad Holian, Gary Holt, Chris
Johnson, Peter Lomdahl, Mark Lutz, Chris Meyers, Paul Saxe, John
Schmidt, Tom Schwaller, Peter-Pike Sloan, Patrick Tullmann, Larry
Virden, Tser-Yuan Yang, Shujia Zhou.

and 

Los Alamos National Laboratory
Lawrence Livermore National Laboratory
Cornell Theory Center
University of Utah
The Scientific Computing and Imaging Group (University of Utah)

(My apologies to anyone I missed...)

If you find SWIG to be useful, I'd like to know about it.

Enjoy!

Dave Beazley
Department of Computer Science
University of Utah
Salt Lake City, Utah  84112
beazley@cs.utah.edu

March 12, 1997







