path: root/README

SWIG (Simplified Wrapper and Interface Generator)

Version: 1.3.22 (September 4, 2004)

Tagline: SWIG is a compiler that integrates C and C++ with
         languages including Perl, Python, Tcl, Guile, Mzscheme,
         Java, Ruby, PHP, Ocaml, Pike, C#, Modula-3, CHICKEN, and
         Allegro Common Lisp.

SWIG reads annotated C/C++ header files and creates wrapper code (glue
code) in order to make the corresponding C/C++ libraries available to
the listed languages, or to extend C/C++ programs with a scripting
language.

This distribution represents the latest development release of SWIG.
The guilty parties working on this are:

Active Developers:
 Dave Beazley (beazley@signal6.com)                     (SWIG core, Python, Tcl, Perl)
 William Fulton (wsf@fultondesigns.co.uk)               (Java, C#, Windows, Cygwin)
 Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de)    (Guile/MzScheme)
 Jason Stewart (jason@openinformatics.com)              (Perl5)
 Lyle Johnson (lyle@users.sourceforge.net)              (Ruby)
 Luigi Ballabio (luigi.ballabio@fastwebnet.it)          (STL wrapping)
 Art Yerkes (ayerkes@speakeasy.net)                     (Ocaml)
 Jonah Beckford (beckford@usermail.com)                 (CHICKEN)
 Mark Rose (mrose@stm.lbl.gov)                          (Directors)
 Henning Thielemann (swig@henning-thielemann.de)        (Modula3)
 Ahmon Dancy (dancy@franz.com)				(Allegro CL)
 Marcelo Matus                                          (Python, Evil C++ testing)
 John Lenz                                              (Guile, MzScheme updates)

Major contributors include:
 Thien-Thi Nguyen (ttn@glug.org)                        (build/test/misc)
 Richard Palmer (richard@magicality.org)                (PHP)
 Sam Liddicott (saml@liddicott.com)                     (PHP)
 Shibukawa Yoshiki                                      (Japanese Translation)
 Loic Dachary                                           (Perl5)
 Masaki Fukushima                                       (Ruby)
 Scott Michel (scottm@cs.ucla.edu)                      (Java directors)
 Tiger Feng (songyanf@cs.uchicago.edu)                  (SWIG core)
 
Past contributors include:
 James Michael DuPont, Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran
 Kovuk, Gary Holt, David Fletcher, Oleg Tolmatcev, Harco de Hilster.
 (See CHANGES for a more complete list).

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

        http://www.swig.org

A SWIG FAQ and other hints can be found on the SWIG Wiki:

       http://www.signal6.com/cgi-bin/wiki.pl

Information about SWIG is also available in Japanese translation at

       http://swig-jp.dyndns.org

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!                      IMPORTANT                         !!!!!!!
!!!!!!!                                                        !!!!!!!
!!!!!!! Previous SWIG users should read the documentation      !!!!!!!
!!!!!!! file Doc/Manual/SWIG.html before trying to use SWIG-1.3!!!!!!!
!!!!!!! on existing SWIG interfaces.  This is the most current !!!!!!!
!!!!!!! documentation that describes new 1.3 features and      !!!!!!!
!!!!!!! incompatibilities.                                     !!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

What's New?
===========

SWIG-1.3.22 summary:
- Improved exception handling and translation of C errors or C++
  exceptions into target language exceptions.
- Improved enum support, mapping to built-in Java 1.5 enums and C#
  enums or the typesafe enum pattern for these two languages.
- Python - much better STL suppport and support for std::wstring,
  wchar_t and FILE *.
- Initial support for Modula3 and Allegro CL.
- 64 bit TCL support.
- Java and C#'s proxy classes are now nearly 100% generated from
  typemaps and/or features for finer control on the generated code.
- SWIG runtime library support deprecation.
- Improved documentation. SWIG now additionally provides documentation
  in the form of a single HTML page as well as a pdf document.
- Enhanced C++ friend declaration support.
- Better support for reference counted classes.
- Various %fragment improvements.
- RPM fixes.
- Various minor improvements and bug fixes for C#, Chicken, Guile, Java, 
  MzScheme, Perl, Php, Ruby and XML.


The SWIG-1.3.x development releases offer a huge number of improvements
over older SWIG-1.1 releases. These improvements include:

   - Support for C++ overloaded functions and methods.
   - Support for C++ smart pointers.
   - Support for C++ namespaces
   - Support for C++ overloaded operators.
   - Support for C++ templates including member templates.
   - Support for C++ template specialization and partial specialization.
   - Support for C++ friend declarations.
   - Parsing support for almost all C/C++ datatypes.
   - Automatic translation of C++ exception specifiers.
   - Contract support.
   - A full C preprocessor with macro expansion. Includes C99 variadic macros.
   - Java, Ruby, MzScheme, PHP4, OCAML, Pike, CHICKEN, XML and C# modules
     added.  Guile module improved.
   - Director support - upcalls for C++ virtual functions into the target 
     language proxy class.
   - Better code generation.   SWIG is better able to make optimizations
     in order to generate less code.
   - Testing framework part of the distribution ("make -k check" support).
   - A lot of minor bug fixes and cleanup.
   - Better Windows support.

If you used SWIG-1.1, a number of old features are missing from SWIG-1.3.

   - The SWIG-1.1 documentation system is gone and hasn't been
     replaced yet.  This is on the long-term to-do list.

   - The Tcl7.x and Perl4 modules are deprecated and no longer
     included.

   - A wide variety of old SWIG command-line options and
     obscure features are gone.

   - A lot of old %pragma directives and obscure undocumented
     customization features have been eliminated.  The same
     functionality is now available through other means.

   - Objective C support doesn't work right now.  No ETA as to
     when it will return.

Although we are making some attempt to preserve backwards
compatibility with interfaces written for SWIG-1.1, SWIG-1.3
incorporates a number of very substantial modifications to type
handling, typemaps, and wrapper code generation.  Therefore, if you
are making extensive use of advanced SWIG features, interfaces written
for SWIG-1.1 may not work.  We apologize for the inconvenience, but
these changes are needed in order to fix a number of annoying
"features" in SWIG-1.1.  Hopefully the list of new features will
provide enough incentive for you to upgrade (and that the
modifications to your interfaces will only be minor).

In addition, SWIG-1.3 makes no attempt to be compatible with SWIG-1.1 at
the C++ API level so language modules written for SWIG-1.1 will most
definitely not work with this release.

See the documentation for details of the SWIG_VERSION preprocessor
symbol if you have backward compatibility issues and need to use more
than one version of SWIG.

The files NEW and CHANGES describe in some detail all of the important
changes that have been made to the system.  Experienced users would be
well advised to read this.

Release Notes
=============
Please see the CHANGES files for a detailed list of bug fixes and
new features. The ANNOUNCE file has a summary of the changes.

Windows Installation
====================
Please see the Doc/Manual/Windows.html file for instructions on installing
SWIG on Windows and running the examples. The Windows distribution is
called swigwin and includes a prebuilt SWIG executable, swig.exe, included in
the same directory as this README file. Otherwise it is exactly the same as
the main SWIG distribution. There is no need to download anything else.

Unix Installation
=================
You must use GNU `make' to build Swig.

http://www.gnu.org/software/make/

To build and install SWIG, simply type the following:

     % ./configure
     % make
     % make install

By default SWIG installs itself in /usr/local.  If you need to install SWIG in
a different location or in your home directory, use the --prefix option
to ./configure.  For example:

     % ./configure --prefix=/home/yourname/projects
     % make
     % make install

Note: the directory given to --prefix must be an absolute pathname.  Do *NOT* use
the ~ shell-escape to refer to your home directory.  SWIG won't work properly
if you do this.

The file INSTALL details more about using configure. Also try

     % ./configure --help.

The configure script will attempt to locate various packages on your machine
including Tcl, Perl5, Python and all the other target languages that SWIG
uses.  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 without having to hack Makefiles.

SWIG used to include a set of runtime libraries for some languages for working
with multiple modules. These are no longer built during the installation stage.
However, users can build them just like any wrapper module as described in
the documentation, Doc/Manual/Modules.html. The CHANGES file also lists some
examples which build the runtime library.

Notes:

(1) If you checked the code out via CVS, you will have to run ./autogen.sh
    before typing 'configure'.    In addition, a full build of SWIG requires
    the use of bison.

Macintosh OS X Installation
============================
SWIG is known to work on various flavors of OS X.  Follow the Unix installation
instructions above.   However, as of this writing, there is still great deal of
inconsistency with how shared libaries are handled by various scripting languages
on OS X.   We've tried to resolve these differences to the extent of our knowledge.
This release was most recently checked with the Panther release of OS X on a 
Macintosh G5 system.   Your mileage may vary.

Users of OS X should be aware that Darwin handles shared libraries and linking in 
a radically different way than most Unix systems.  In order to test SWIG and run
the examples, SWIG configures itself to use flat namespaces and to allow undefined 
symbols (-flat_namespace -undefined suppress).  This mostly closely follows the Unix 
model and makes it more likely that the SWIG examples will work with whatever 
installation of software you might have.   However, this is generally not the recommended
technique for building larger extension modules.  Instead, you should utilize
Darwin's two-level namespaces.  Some details about this can be found here

http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html

Needless to say, you might have to experiment a bit to get things working at first.

Testing
=======
If you want to test SWIG before installation, type the following:

    % make -k check

'make -k check' requires at least one of the target languages to be
installed.  If it fails, it may mean that you have an uninstalled
language module or that the file 'Examples/Makefile' has been
incorrectly configured.  It may also fail due to compiler issues such
as broken C++ compiler.  Even if 'make -k check' fails, there is a
pretty good chance SWIG still works correctly---you will just have to
mess around with one of the examples and some makefiles to get it to work.

The testing suite executed by 'make -k check' is designed to stress-test
many parts of the implementation including obscure corner cases. If some
of these tests fail or generate warning messages, there is no reason for
alarm---the test may be related to some new SWIG feature or a difficult bug
that we're trying to resolve.  Chances are that SWIG will work just fine
for you.

Also, SWIG's support for C++ is sufficiently advanced that certain
tests may fail on older C++ compilers (for instance if your compiler
does not support member templates).   These errors are harmless if you
don't intend to use these features in your own programs.

Note: The test-suite currently contains around 250 tests.  If you
have many different target languages installed and a slow machine, it
might take more than an hour to run the test-suite.

Note: Some of the tests and examples may depend on SWIG runtime libraries.
These are not built by default.  Type 'make -k runtime' to build the libraries
if needed.

Examples
========
The Examples directory contains a variety of examples of using SWIG
and it has some browsable documentation.  Simply point your browser to
the file "Example/index.html".

The Examples directory also includes Visual C++ project (.dsp) files for
building some of the examples on Windows.

Known Issues
============
There are minor bugs, details of which are in the bug tracker, see
http://www.swig.org/bugs.html.

Troubleshooting
===============
In order to operate correctly, SWIG relies upon a set of library
files.  If after building SWIG, you get error messages like this,

    % swig foo.i
    :1. Unable to find 'swig.swg'
    :3. Unable to find 'tcl8.swg'

it means that SWIG has either been incorrectly configured or
installed.  To fix this:

    1.  Make sure you remembered to do a 'make install' and that
        the installation actually worked.  Make sure you have
        write permission on the install directory.

    2.  If that doesn't work, type 'swig -swiglib' to find out
        where SWIG thinks its library is located.

    3.  If the location is not where you expect, perhaps
        you supplied a bad option to configure.  Use
        ./configure --prefix=pathname to set the SWIG install
        location.   Also, make sure you don't include a shell
        escape character such as ~ when you specify the path.

    4.  The SWIG library can be changed by setting the SWIG_LIB
        environment variable.  However, you really shouldn't
        have to do this.

If you are having other troubles, you might look at the SWIG Wiki at
http://www.signal6.com/cgi-bin/wiki.pl.

Documentation
=============
The Doc/Manual directory contains the most recent set of updated
documentation for this release.  The documentation is available in
a single page html format, multiple page html format or pdf format,
see Doc/Manual/index.html.

This is a development release and the documentation is largely, but 
not entirely up to date.  We are working on it, but there
was a lot of old documentation and it is taking some time to
update and complete. Please be patient or volunteer to help.

!! The most up-to-date information concerning new features in SWIG-1.3 is the
!! file Doc/Manual/SWIG.html.

There is some technical developer documentation available in the
Doc/Devel subdirectory.  This is not necessarily up-to-date, but it
has some information on SWIG internals.

Participate!
============
Please report any errors and submit patches (if possible)!  We only
have access to a limited variety of hardware (Linux, Solaris, OS-X,
and Windows). All contributions help.

If you would like to join the SWIG development team or contribute a
language module to the distribution, please contact the swig-dev
mailing list, details at http://www.swig.org/mail.html.

 -- The SWIG Maintainers