3db3d59a14
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@4546 626c5289-ae23-0410-ae9c-e8d60b6d4f22
288 lines
11 KiB
Text
288 lines
11 KiB
Text
SWIG (Simplified Wrapper and Interface Generator)
|
|
|
|
Version: 1.3.17 (November 22, 2002)
|
|
|
|
$Header$
|
|
|
|
Tagline: SWIG is a compiler that integrates C and C++ with
|
|
languages including Perl, Python, Tcl, Guile, Mzscheme,
|
|
Java, Ruby, PHP, Ocaml and CHICKEN.
|
|
|
|
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,
|
|
aiming to replace versions 1.1p5 and 1.1-883. The guilty parties
|
|
working on this are:
|
|
|
|
Dave Beazley (beazley@cs.uchicago.edu) (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)
|
|
Richard Palmer (richard@magicality.org) (PHP)
|
|
Luigi Ballabio (luigi.ballabio@fastwebnet.it) (Macintosh, STL wrapping)
|
|
Sam Liddicott (saml@liddicott.com) (PHP)
|
|
Art Yerkes (ayerkes@speakeasy.net) (Ocaml)
|
|
Thien-Thi Nguyen (ttn@glug.org) (build/test/misc)
|
|
Tiger Feng (songyanf@cs.uchicago.edu) (SWIG core)
|
|
Jonah Beckford (beckford@usermail.com) (CHICKEN)
|
|
|
|
Major contributors include:
|
|
Shibukawa Yoshiki (Japanese Translation)
|
|
Marcelo Matus (Evil C++ testing)
|
|
Loic Dachary (Perl5)
|
|
Masaki Fukushima (Ruby)
|
|
James Michael DuPont(mdupont777@yahoo.com) (C#/PNet Support with the original code from Neil Cawse)
|
|
|
|
Past contributors include:
|
|
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://swig.cs.uchicago.edu/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 SWIG1.3 !!!!!!!
|
|
!!!!!!! on existing SWIG interfaces. This is the most current !!!!!!!
|
|
!!!!!!! documentation that describes new 1.3 features and !!!!!!!
|
|
!!!!!!! incompatibilities. !!!!!!!
|
|
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
|
What's New?
|
|
===========
|
|
The most notable changes since SWIG1.1 include the following:
|
|
|
|
- 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,
|
|
specialization, and partial specialization.
|
|
|
|
- Parsing support for almost all C/C++ datatypes.
|
|
|
|
- A full C preprocessor with macro expansion.
|
|
Includes C99 variadic macro support.
|
|
|
|
- Java, Ruby, MzScheme, PHP4, OCAML, Pike, CHICKEN and XML modules
|
|
added. Guile module improved.
|
|
|
|
- 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 SWIG1.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 SWIG1.1, SWIG1.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 SWIG1.1 may not work. We apologize for the inconvenience, but
|
|
these changes are needed in order to fix a number of annoying
|
|
"features" in SWIG1.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, SWIG1.3 makes no attempt to be compatible with SWIG1.1 at
|
|
the C++ API level so language modules written for SWIG1.1 will most
|
|
definitely not work with this release.
|
|
|
|
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.
|
|
|
|
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
|
|
=================
|
|
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 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Note: 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 more than 170 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.
|
|
|
|
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 now includes Visual C++ project (.dsp) files for
|
|
building some of the examples on Windows (new in SWIG1.3.7).
|
|
|
|
Known Issues
|
|
============
|
|
The SWIG-1.3.15 release includes a number of substantial changes to existing
|
|
language modules. These changes include modifications to the build environment
|
|
and the wrapper code itself. Certain examples may not compile or may need
|
|
minor changes to work.
|
|
|
|
Please see the CHANGES file for a detailed list of changes.
|
|
|
|
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://swig.cs.uchicago.edu/cgi-bin/wiki.pl.
|
|
|
|
Documentation
|
|
=============
|
|
The Doc/Manual directory contains the most recent set of updated
|
|
documentation for this release. As this is a development release, the
|
|
documentation is not entirely up to date and is being worked on. We
|
|
are working on it, but there is a lot of old documentation and it is going
|
|
to take time to complete. Please be patient or volunteer to help.
|
|
|
|
!! The most up-to-date information concerning new features in SWIG1.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 swig-dev@cs.uchicago.edu.
|
|
|
|
-- The SWIG Maintainers
|
|
|
|
|
|
|