| SWIG (Simplified Wrapper and Interface Generator) |
| |
| Version: 1.3.26 (October 9, 2005) |
| |
| 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, and |
| Common Lisp (CLISP, Allegro CL, UFFI). |
| |
| 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 (dave-swig@dabeaz.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) |
| 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, Chicken module) |
| Surendra Singhi (efuzzyone@netscape.net) (CLISP) |
| Charlie Savage (cfis@interserv.com) (Ruby) |
| |
| Major contributors include: |
| Lyle Johnson (lyle@users.sourceforge.net) (Ruby) |
| 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.dabeaz.com/cgi-bin/wiki.pl |
| |
| Information about SWIG is also available in Japanese translation at |
| |
| http://swig-jp.dyndns.org |
| |
| !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| !!!!!!! 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.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. |
| |
| 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.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 |
| 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 |
| |
| |
| |