SWIG (Simplified Wrapper and Interface Generator) Version: 1.3.10 (December 10, 2001) $Header$ Tagline: SWIG is a compiler that integrates C and C++ with languages including Perl, Python, Tcl, Guile, Mzscheme, Java, Ruby, and PHP. 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) William Fulton (wsf@fultondesigns.co.uk) (Java) Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de) (Guile/MzScheme) Loic Dachary (loic@ceic.com) (Perl5) Jason Stewart (jason@openinformatics.com) (Perl5) Thien-Thi Nguyen (ttn@glug.org) (Testing/Misc) Lyle Johnson (ljohnson@resgen.com) (Ruby) Masaki Fukushima (fukusima@goto.info.waseda.ac.jp) (Ruby) Richard Palmer (richard@magicality.org) (PHP) 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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!! 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 operators. - Support for C++ templates. - Improved support for overloaded functions/methods. - Parsing support for almost all C/C++ datatypes. - Pointers to members are now supported in the parser and by the Python module. - Improved support for pointers to functions and callbacks. - SWIG now has a full C preprocessor. - Code generation for the Tcl and Python modules has been substantially improved both in terms of size and runtime efficiency (Perl5 is coming along too). - The Guile module is stable. It represents C pointers as smobs and supports the Guile module system and exceptions. - Java, Ruby, MzScheme, PHP4 modules added. - Redesigned implementation of typemaps. Typemaps can now be defined for groups of consecutive function arguments. This has been a long requested feature that now works. - 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. Here are a few missing features: - 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. - The Perl5 module is need in some repair and may not work with ActivePerl. We are looking for volunteers to help us with this. - 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 things such as 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 -k check # this step is optional (see note below) % 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 -k check % 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. (2) 'make -k check' is a new feature that requires at least one of the target languages to be installed and which performs compile/link level testing of the examples. 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 first. 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). 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 remembed 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 an unstable 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 documentation and it is going to take time to complete. Please be patient. !! The most up-to-date information concerning new features in SWIG1.3 is the !! file Doc/Manual/SWIG.html. There is some technical 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, 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 beazley@cs.uchicago.edu. -- The SWIG Maintainers