| SWIG (Simplified Wrapper and Interface Generator) |
| |
| Version: 1.3.35 (24 June 2008) |
| |
| Tagline: SWIG is a compiler that integrates C and C++ with languages |
| including Perl, Python, Tcl, Ruby, PHP, Java, Ocaml, Lua, |
| Scheme (Guile, MzScheme, CHICKEN), Pike, C#, Modula-3, |
| Common Lisp (CLISP, Allegro CL, CFFI, UFFI), Octave and R. |
| |
| 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: |
| William Fulton (wsf@fultondesigns.co.uk) (SWIG core, Java, C#, Windows, Cygwin) |
| Olly Betts (olly@survex.com) (PHP) |
| John Lenz (Guile, MzScheme updates, Chicken module, runtime system) |
| Mark Gossage (mark@gossage.cjb.net) (Lua) |
| Joseph Wang (joe@gnacademy.org) (R) |
| Gonzalo Garramuno (ggarra@advancedsl.com.ar) (Ruby, Ruby's UTL) |
| Xavier Delacour (xavier.delacour@gmail.com) (Octave) |
| |
| Major contributors include: |
| Dave Beazley (dave-swig@dabeaz.com) (SWIG core, Python, Tcl, Perl) |
| Henning Thielemann (swig@henning-thielemann.de) (Modula3) |
| Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de) (Guile, MzScheme) |
| Luigi Ballabio (luigi.ballabio@fastwebnet.it) (STL wrapping) |
| Mikel Bancroft (mikel@franz.com) (Allegro CL) |
| Surendra Singhi (efuzzyone@netscape.net) (CLISP, CFFI) |
| Marcelo Matus (mmatus@acms.arizona.edu) (SWIG core, Python, UTL[python,perl,tcl,ruby]) |
| Art Yerkes (ayerkes@speakeasy.net) (Ocaml) |
| Lyle Johnson (lyle@users.sourceforge.net) (Ruby) |
| Charlie Savage (cfis@interserv.com) (Ruby) |
| Thien-Thi Nguyen (ttn@glug.org) (build/test/misc) |
| Richard Palmer (richard@magicality.org) (PHP) |
| Sam Liddicott - Anonova Ltd (saml@liddicott.com) (PHP) |
| Tim Hockin - Sun Microsystems (thockin@sun.com) (PHP) |
| Kevin Ruland (PHP) |
| Shibukawa Yoshiki (Japanese Translation) |
| Jason Stewart (jason@openinformatics.com) (Perl5) |
| Loic Dachary (Perl5) |
| David Fletcher (Perl5) |
| Gary Holt (Perl5) |
| Masaki Fukushima (Ruby) |
| Scott Michel (scottm@cs.ucla.edu) (Java directors) |
| Tiger Feng (songyanf@cs.uchicago.edu) (SWIG core) |
| Mark Rose (mrose@stm.lbl.gov) (Directors) |
| Jonah Beckford (beckford@usermail.com) (CHICKEN) |
| Ahmon Dancy (dancy@franz.com) (Allegro CL) |
| Dirk Gerrits (Allegro CL) |
| Neil Cawse (C#) |
| Harco de Hilster (Java) |
| Alexey Dyachenko (dyachenko@fromru.com) (Tcl) |
| Bob Techentin (Tcl) |
| Martin Froehlich <MartinFroehlich@ACM.org> (Guile) |
| Marcio Luis Teixeira <marciot@holly.colostate.edu> (Guile) |
| Duncan Temple Lang (R) |
| |
| Past contributors include: |
| James Michael DuPont, Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran |
| Kovuk, Oleg Tolmatcev, Tal Shalif, Lluis Padro, Chris Seatory, Igor Bely, Robin Dunn |
| (See CHANGES for a more complete list). |
| |
| Portions also copyrighted by companies/corporations; |
| Network Applied Communication Laboratory, Inc |
| Information-technology Promotion Agency, Japan |
| |
| 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.dabeaz.com/cgi-bin/wiki.pl |
| |
| |
| !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| !!!!!!! IMPORTANT !!!!!!! |
| !!!!!!! !!!!!!! |
| !!!!!!! Previous SWIG-1.1 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.36 summary: |
| - Enhancement to directors to wrap all protected members |
| - Optimisation feature for objects returned by value |
| - A few bugs fixes in the PHP, Java, Ruby, R, C#, Python, Lua and |
| Perl modules |
| - Other minor generic bug fixes |
| |
| SWIG-1.3.35 summary: |
| - Octave language module added |
| - Bug fixes in Python, Lua, Java, C#, Perl modules |
| - A few other generic bugs and runtime assertions fixed |
| |
| SWIG-1.3.34 summary: |
| - shared_ptr support for Python |
| - Support for latest R - version 2.6 |
| - Various minor improvements/bug fixes for R, Lua, Python, Java, C# |
| - A few other generic bug fixes, mainly for templates and using statements |
| |
| SWIG-1.3.33 summary: |
| - Fix regression for Perl where C++ wrappers would not compile |
| - Fix regression parsing macros |
| |
| SWIG-1.3.32 summary: |
| - shared_ptr support for Java and C# |
| - Enhanced STL support for Ruby |
| - Windows support for R |
| - Fixed long-standing memory leak in PHP Module |
| - Numerous fixes and minor enhancements for Allegrocl, C#, cffi, Chicken, Guile, |
| Java, Lua, Ocaml, Perl, PHP, Python, Ruby, Tcl. |
| - Improved warning support |
| |
| SWIG-1.3.31 summary: |
| - Python modern classes regression fix |
| |
| SWIG-1.3.30 summary: |
| - Python-2.5 support |
| - New language module: R |
| - Director support added for C# |
| - Numerous director fixes and improvements |
| - Improved mingw/msys support |
| - Better constants support in Guile and chicken modules |
| - Support for generating PHP5 class wrappers |
| - Important Java premature garbage collection fix |
| - Minor improvements/fixes in cffi, php, allegrocl, perl, chicken, lua, ruby, |
| ocaml, python, java, c# and guile language modules |
| - Many many other bug fixes |
| |
| SWIG-1.3.29 summary: |
| - Numerous important bug fixes |
| - Few minor new features |
| - Some performance improvements in generated code for Python |
| |
| SWIG-1.3.28 summary: |
| - More powerful renaming (%rename) capability. |
| - More user friendly warning handling. |
| - Add finer control for default constructors and destructors. We discourage |
| the use of the 'nodefault' option, which disables both constructors and |
| destructors, leading to possible memory leaks. Use instead 'nodefaultctor' |
| and/or 'nodefaultdtor'. |
| - Automatic copy constructor wrapper generation via the 'copyctor' option/feature. |
| - Better handling of Windows extensions and types. |
| - Better runtime error reporting. |
| - Add the %catches directive to catch and dispatch exceptions. |
| - Add the %naturalvar directive for more 'natural' variable wrapping. |
| - Better default handling of std::string variables using the %naturalvar directive. |
| - Add the %allowexcept and %exceptionvar directives to handle exceptions when |
| accessing a variable. |
| - Add the %delobject directive to mark methods that act like destructors. |
| - Add the -fastdispatch option to enable smaller and faster overload dispatch |
| mechanism. |
| - Template support for %rename, %feature and %typemap improved. |
| - Add/doc more debug options, such as -dump_module, -debug_typemaps, etc. |
| - Unified typemap library (UTL) potentially providing core typemaps for all |
| scripting languages based on the recently evolving Python typemaps. |
| - New language module: Common Lisp with CFFI. |
| - Python, Ruby, Perl and Tcl use the new UTL, many old reported and hidden |
| errors with typemaps are now fixed. |
| - Initial Java support for languages using the UTL via GCJ, you can now use |
| Java libraries in your favorite script language using gcj + swig. |
| - Tcl support for std::wstring. |
| - PHP4 module update, many error fixes and actively maintained again. |
| - Allegrocl support for C++, also enhanced C support. |
| - Ruby support for bang methods. |
| - Ruby support for user classes as native exceptions. |
| - Perl improved dispatching in overloaded functions via the new cast and rank |
| mechanism. |
| - Perl improved backward compatibility, 5.004 and later tested and working. |
| - Python improved backward compatibility, 1.5.2 and later tested and working. |
| - Python can use the same cast/rank mechanism via the -castmode option. |
| - Python implicit conversion mechanism similar to C++, via the %implicitconv |
| directive (replaces and improves the implicit.i library). |
| - Python threading support added. |
| - Python STL support improved, iterators are supported and STL containers can |
| use now the native PyObject type. |
| - Python many performance options and improvements, try the -O option to test |
| all of them. Python runtime benchmarks show up to 20 times better performance |
| compared to 1.3.27 and older versions. |
| - Python support for 'multi-inheritance' on the python side. |
| - Python simplified proxy classes, now swig doesn't need to generate the |
| additional 'ClassPtr' classes. |
| - Python extended support for smart pointers. |
| - Python better support for static member variables. |
| - Python backward compatibility improved, many projects that used to work |
| only with swig-1.3.21 to swig-1.3.24 are working again with swig-1.3.28 |
| - Python test-suite is now 'valgrinded' before release, and swig also |
| reports memory leaks due to missing destructors. |
| - Minor bug fixes and improvements to the Lua, Ruby, Java, C#, Python, Guile, |
| Chicken, Tcl and Perl modules. |
| |
| SWIG-1.3.27 summary: |
| - Fix bug in anonymous typedef structures which was leading to strange behaviour |
| |
| SWIG-1.3.26 summary: |
| - New language modules: Lua, CLISP and Common Lisp with UFFI. |
| - Big overhaul to the PHP module. |
| - Change to the way 'extern' is handled. |
| - Minor bug fixes specific to C#, Java, Modula3, Ocaml, Allegro CL, |
| XML, Lisp s-expressions, Tcl, Ruby and Python modules. |
| - Other minor improvements and bug fixes. |
| |
| SWIG-1.3.25 summary: |
| - Improved runtime type system. Speed of module loading improved in |
| modules with lots of types. SWIG_RUNTIME_VERSION has been increased |
| from 1 to 2, but the API is exactly the same; only internal changes |
| were made. |
| - The languages that use the runtime type system now support external |
| access to the runtime type system. |
| - Various improvements with typemaps and template handling. |
| - Fewer warnings in generated code. |
| - Improved colour documentation. |
| - Many C# module improvements (exception handling, prevention of early |
| garbage collection, C# attributes support added, more flexible type |
| marshalling/asymmetric types.) |
| - Minor improvements and bug fixes specific to the C#, Java, TCL, Guile, |
| Chicken, MzScheme, Perl, Php, Python, Ruby and Ocaml modules). |
| - Various other bug fixes and memory leak fixes. |
| |
| SWIG-1.3.24 summary: |
| - Improved enum handling |
| - More runtime library options |
| - More bugs fixes for templates and template default arguments, directors |
| and other areas. |
| - Better smart pointer support, including data members, static members |
| and %extend. |
| |
| SWIG-1.3.23 summary: |
| - Improved support for callbacks |
| - Python docstring support and better error handling |
| - C++ default argument support for Java and C# added. |
| - Improved c++ default argument support for the scripting languages plus |
| option to use original (compact) default arguments. |
| - %feature and %ignore/%rename bug fixes and mods - they might need default |
| arguments specified to maintain compatible behaviour when using the new |
| default arguments wrapping. |
| - Runtime library changes: Runtime code can now exist in more than one module |
| and so need not be compiled into just one module |
| - Further improved support for templates and namespaces |
| - Overloaded templated function support added |
| - More powerful default typemaps (mixed default typemaps) |
| - Some important %extend and director code bug fixes |
| - Guile now defaults to using SCM API. The old interface can be obtained by |
| the -gh option. |
| - Various minor improvements and bug fixes for C#, Chicken, Guile, Java, |
| MzScheme, Perl, Python and Ruby |
| - Improved dependencies generation for constructing Makefiles. |
| |
| 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, Python, 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. A summary of the changes is included in this README file. |
| |
| 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. |
| |
| Please see the Documentation section below on installing documentation as |
| none is installed by default. |
| |
| 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 SVN, 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. Note that if you have more than one CPU/core, then you can use |
| parallel make can be used to speed up the check as it does take quite some |
| time to run, for example: |
| |
| % make -j2 -k check |
| |
| 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. |
| |
| 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 known 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.dabeaz.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 |
| three different formats, each of which contains identical content. |
| These format are, pdf (SWIGDocumentation.pdf), single |
| page html (Doc/Manual/SWIGDocumentation.html) or multiple page html |
| (other files in Doc/Manual). Please select your chosen format and |
| copy/install to wherever takes your fancy. |
| |
| 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. |
| |
| 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 |
| |
| |
| |