SWIG (Simplified Wrapper and Interface Generator) Version 1.0 September 8, 1996 Dave Beazley Department of Computer Science University of Utah Salt Lake City, Utah 84122 beazley@cs.utah.edu 1. Welcome! ------------- SWIG is a tool that I have developed to solve real problems and to make C/C++ programming more enjoyable. In a nutshell, SWIG is a compiler that lets you take collections of C/C++ functions, variables, and constants and add them to interpreted scripting languages including Tcl, Python, and Perl. By doing this, you can create interactive and modular C/C++ programs and do alot of things that would be difficult to do entirely in C/C++. I primarily use SWIG for rapid prototyping, debugging, control, and testing of C/C++ programs. SWIG is primarily designed to be a powerful no-nonsense tool for easily mixing scripting languages with C or C++. Many scripting languages already have tools to do this, but they always seem to be special purpose, poorly documented, and language specific. On the other hand, one might consider using a sophisticated interface builder, but these almost always seem to make things too complicated---especially when you'd really like to be working on the real problem at hand. SWIG fits somewhere in the middle of this spectrum. On one hand, SWIG is a "simple" tool that is extremely easy to learn and use when you just want to build an interface without worrying about it. On the other hand, SWIG is (hopefully) well-documented, supports multiple target languages, general purpose, and can be used for larger projects. 2. Currently Supported Languages ---------------------------------- To use SWIG, you will need at least one of the following scripting languages : Tcl7.3, Tk3.6 (and all newer versions) [incr Tcl] 2.1 Python1.3 (or newer) Perl5 Perl4 Guile-iii If you don't have any of these, SWIG will still compile, but it won't be particularly useful. 3. Installation ----------------- To compile and use SWIG, you will need the following on your machine: A C++ compiler (ie. g++) An ANSI C compiler (ie. gcc) yacc or bison To compile and install SWIG, type the following : ./configure make make install There are a number of configuration options that you can give to 'configure' : --prefix=/usr/local Set the installation prefix. SWIG installs into /usr/local by default. --exec_prefix=/usr/local Set the prefix used to install platform specific files (binaries and libraries). Use this if the location is different than that given with --prefix. --with-lang={TCL,PERL5,PYTHON,PERL4,GUILE3} This lets you choose the default SWIG target language. By default, SWIG chooses TCL, but you can select another as shown : ./configure --with-lang=PYTHON --with-doc={ASCII,LaTeX,HTML,NODOC} This lets you choose the default SWIG documentation method. By default, SWIG chooses ASCII. To test the SWIG parser after compilation, type 'make test'. This will print out lots of stuff and may take awhile. However, if it works you will get a message at the end. If the tests core dump or die an unexpected death, please send me e-mail! NOTE : The test process will print out alot of warning messages and even some error messages. This is part of the test to make sure the SWIG parser is working correctly. If the test is successful, you should see a notice near the end saying so. If the tests core dumps or stops, then there is a problem. 4. Examples ------------ The 'Examples' directory contains a bunch of SWIG examples for various scripting languages. All of the examples rely on the file 'Makefile.template' located in the top-level directory. The 'configure' script will attempt to locate various scripting languages on your machine and update the contents of Makefile.template automatically. However, this process is not foolproof, so you may need to edit this file by hand afterwards (you only need to do this if you've tried to compile an example and it doesn't work). 5. Resources -------------- Up-to-date SWIG related information can be found at http://www.cs.utah.edu/~beazley/SWIG/swig.html SWIG source code and software updates are also available via anonymous ftp at ftp://ftp.cs.utah.edu/pub/beazley/SWIG You can join the SWIG mailing list by sending a message containing the line "subscribe swig" to Majordomo@cs.utah.edu. The SWIG mailing list is a forum for discussing various applications of SWIG, installation problems, ideas for system improvements and future work. 6. Installation Problems ------------------------- I have tested the installation on the following platforms : - SunOS 4.1.3 - Solaris - Irix 5.3 - Irix 6.1 - HPUX - AIX 4.1 - Linux - MkLinux - MachTen - UNICOS SWIG development has primarily taken place on Solaris 2.5.1, Irix 5.3, and MkLinux. I've tested most of the examples on these platforms. If you've tried everything and can't get SWIG to compile, please send me e-mail at beazley@cs.utah.edu, and we'll try to figure it out. 7. Documentation ----------------- A postscript version of the user manual is in SWIG_Doc.ps. This document is 120 pages long, but it covers almost all aspects of SWIG including how to use it, a collection of examples, and technical information about how SWIG is implemented. Don't let the manual scare you! SWIG is easy enough to use that you can probably start using it without reading the manual. However, at some point you will probably want to know more so I hope that the manual explains everything you need to know. Besides, I hate black boxes... If you would prefer to save the life of a small tree, the manual is also available as an Adobe PDF file and in HTML. Both are available at http://www.cs.utah.edu/~beazley/SWIG/swig.html (All three versions of the documentation are generated from the same source and are identical in content.) 8. Incompatibilities --------------------- These release incorporate major changes to both the Perl5 and Python language modules--and a few incompatibilities. I apologize for this, but both of those modules have been experimental in the past. I believe that the following changes make them more solid. - Global variable handling in Python : Global variables are now accessed through a special 'cvar' object created in each module. For example : C Code : double My_variable; Python : module.cvar.My_variable (where module is your module name). This new representation allows the variables to be used in arithmetic expressions and other things. ie : a = module.cvar.My_variable *3.4 See Appendix A of the SWIG manual for more information about this. - Pointers in Perl5 Pointers are now represented as blessed scalar values, which is the same representation used by xsubpp generated code. All scripts should still work except for those which do pointer comparisons. Pointer comparisons should now be done as follows : ptr1 = new_Pointer(); ptr2 = new_Pointer(); if ($$ptr == $$ptr2) { ... do something ... } - %typedef. Some old SWIG interface files used this directive. SWIG 1.0 still supports it, but it must now be terminated by a semicolon or you'll get a syntax error. As far as I know, all of the SWIG examples and library files are now up to date. 9. Bug Reports ---------------- Bug reports should be submitted to beazley@cs.utah.edu. I am committed to providing a quality package and will make every attempt to fix bugs as soon as possible. 10. Legal Stuff --------------- SWIG is completely free. You can do whatever you want with it (including distribution), provided that you do two things. 1) Keep all of the copyright notices intact and don't claim that you wrote it, and 2) Don't sue me if it breaks. Otherwise, have fun. 11. Disclaimer ---------------- While I believe that SWIG is reasonably stable, I'm always tinkering with it and trying to make it better. There may be a few bugs hiding around so if you experience any problems let me know. If you think that SWIG is missing some capability that would be really cool to have, post a message on the SWIG mailing list. Most of the previous suggestions have already been incorporated into this release. 12. Special Thanks ------------------- SWIG would not be possible without the contributions of people who tried out the beta versions and offered feedback. Looking back through my logs and e-mail, I'd like to acknowledge the people who have sent in bug-reports and ideas. In no particular order : Al Davis, Bill Ashmanskas, Bill Eme, Bill Janssen, Brad Holian, Brian MacWhinney, Chris Johnson, Chris Myers, Dave Weinstein, David Ascher, Erik D. Hals, Etienne de Bruin, Fred Higgs, Fredrik Lundh, Gary Lindstrom, Guido van Rossom, Han-Wei Shen, Jacob Levy, Jacquies Marcoux, Javier Contreras, Jean-Pierre Heber, Jeff Johnson, Jeng Wei Pan, Jian L. Zhen, Jim Hugunin, Jim Meyering, John Buckman, John Carter, John Schmidt, Kasper Peeters, Ken Robbins, Kenneth Martin, Kurtis Bleeker, Larry Virden, Mark Harrison, Matthew O'Brien, Mike Hartshorn, Mike Parker, Mike Weiblen, Naftali Schwartz, Patrick Tullmann, Paul Dubois, Pete Hannan, Peter Lomdahl, Peter-Pike Sloan, Randy Melton, Ricky Lui, Shujia Zhou, Simon Warfield, Steve Parker, Tim Germann, Tim Germann, Tom Schwaller, Tser-Yuan (Brian) Yang, W. T. Hewitt, Bart Robinson. (My apologies to anyone I missed...) I'd also like to acknowledge those individuals and organizations who have made significant contributions to the development of SWIG : - John Buckman - Larry Virden - Tom Schwaller - Patrick Tullman - John Schmidt - Kurtis Bleeker - Peter Lomdahl - Chris Johnson - University of Utah, Department of Computer Science. - Los Alamos National Laboratory - Lawrence Livermore National Laboratory - And everyone I talked to at the Python and Tcl workshops. If you find this package useful, I'd like to hear about it. If you make a cool extension, share it! Enjoy! Dave Beazley beazley@cs.utah.edu September 8, 1996