diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 575 |
1 files changed, 575 insertions, 0 deletions
@@ -0,0 +1,575 @@ +SWIG (Simplified Wrapper and Interface Generator) + +Version: 1.3.40 (18 August 2009) + +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 (joequant@gmail.com) (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) + Miklos Vajna <vmiklos@frugalware.org> (PHP directors) + +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.40 summary: +- SWIG now supports directors for PHP. +- PHP support improved in general. +- Octave 3.2 support added. +- Various bug fixes/enhancements for Allegrocl, C#, Java, Octave, Perl, + Python, Ruby and Tcl. +- Other generic fixes and minor new features. + +SWIG-1.3.39 summary: +- Some new small feature enhancements. +- Improved C# std::vector wrappers. +- Bug fixes: mainly Python, but also Perl, MzScheme, CFFI, Allegrocl + and Ruby + +SWIG-1.3.38 summary: +- Output directory regression fix and other minor bug fixes + +SWIG-1.3.37 summary: +- Python 3 support added +- SWIG now ships with a version of ccache that can be used with SWIG. + This enables the files generated by SWIG to be cached so that repeated + use of SWIG on unchanged input files speeds up builds quite considerably. +- PHP 4 support removed and PHP support improved in general +- Improved C# array support +- Numerous Allegro CL improvements +- Bug fixes/enhancements for Python, PHP, Java, C#, Chicken, Allegro CL, + CFFI, Ruby, Tcl, Perl, R, Lua. +- Other minor generic bug fixes and enhancements + +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 + + + |