SWIG (Simplified Wrapper and Interface Generator) Version 1.0 Beta 2 (O'Reilly Distribution) Dave Beazley May 16, 1996 1. Introduction ----------------- SWIG is a tool for automatically generating the wrapper code needed to link collections of functions written in C/C++ with interpreted scripting languages. Currently, SWIG supports : - Python 1.3 - Tcl - Perl4 - Perl5 - Guile-iii Using SWIG, it is possible to greatly simplify interface development and to put interesting interfaces on existing applications with little effort. 2. Resources (and disclaimer) ------------------------------- Up-to-date SWIG related information can be found at http://www.cs.utah.edu/~beazley/SWIG/swig.html As this is beta release software, there may be problems compiling and installing this package. I have tested the Installation under Irix, Solaris, SunOS, HPUX, Linux, and MachTen. If you have problems compiling, please check the above web-page to see if there is a fix, or contact me via e-mail at beazley@cs.utah.edu. SWIG source code and software updates are also available via anonymous ftp at ftp://ftp.cs.utah.edu/pub/beazley/SWIG !!!! JOIN THE SWIG MAILING LIST !!!! 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, and ideas for future development. 3. Installation ----------------- SWIG needs both a properly installed C++ compiler and bison/yacc in order to compile. In order to install, edit the Makefile manually by following the instructions contained within it. Fortunately, you only need to set a few default values such as the directory where you want SWIG to be installed. After you've edited the Makefile, type "make" to compile SWIG. In order to install SWIG, type "make install" to copy the binary and library files to their final location. I've tried this Makefile on a wide variety of machines without problems. If the installation should fail for some reason, here's where files are installed SWIG1.0b1/wrap --> /usr/local/bin/wrap SWIG1.0b1/swig.h --> /usr/local/include/swig.h SWIG1.0b1/libswig.a --> /usr/local/lib/libswig.a SWIG1.0b1/lib_swig --> /usr/local/lib/lib_swig If you don't have bison, you can try using yacc instead. However, some versions of yacc aren't very C++ friendly so this may not work at all. If neither yacc or bison work, try the following : % make noyacc If this still doesn't work, send e-mail to beazley@cs.utah.edu or yell at your system admin to install bison (well, maybe you should ask nicely instead of yelling). NOTE : SWIG does not require any of the supported target languages to compile. If you don't have all of the target languages (Tcl, Perl4, Perl5, Python, or Guile) don't worry about it. 4. A full SWIG installation ---------------------------- SWIG isn't going to be too useful by itself. You'll want to install Tcl/Tk, Perl, Python, or Guile depending on what you want to use. Here's how I have SWIG set-up on my machine (arrows indicate symbolic links): /usr/local/bin/ wrap (The swig executable) wish tclsh expect expectk perl perl5 guile python /usr/local/include tcl.h --> tcl7.4.h (I just point these to the most current tk.h --> tk4.0.h version) expect.h expect_cf.h expect_com.h expect_tcl.h Py/ perl4/ --> /usr/local/src/perl-4.035 perl5/ --> /usr/local/src/perl5.001m guile/ --> /usr/local/src/guile-src/=inst/include /usr/local/lib libtcl.a --> libtcl7.4.a libtk.a --> libtk4.0.a libexpect.a libexpectk.a perl4/ (Perl4 programs of various sorts) perl5/ (Perl5 programs) guile/ --> /usr/local/src/guile-src/=inst/lib uperl.o --> /usr/local/src/perl-4.035/uperl.o swig_lib/ (SWIG Library directory) The main concern is that in order to link with systems such as Perl, you will need to use header files supplied in the Perl source directory. There's no right way to set this up, but it's easy to remember if everything is in a common location such as /usr/local/include. 5. Notes to system administrators --------------------------------- In order for SWIG to be useful, header files from the Perl4, Perl5, and Guile source directories need to be user-accessible. If SWIG is being installed for general use, these directories should be made available in an easily accessible location. 6. Notes to users ------------------- SWIG requires proper installations of Tcl, Perl4, Perl5, Python, or Guile (depending on what you want to do of course). If you don't have these system available, you can easily install them yourself into a private directories such as the following : ~/packages/bin ~/packages/lib ~/packages/include All of the above programs can be found on the Internet (the SWIG page also has links to sites containing Tcl, Perl, Python, and Guile). Follow the installation instructions on how to install them into your own directory (usually you can just do a "configure --prefix=~/packages"). Once installed in your directory, you can set up symbolic links like in part 4. Then, when compiling, just set the -I and -L flags to point to your own include and lib directories. 7. Documentation ----------------- A postscript version of the user manual is in SWIG_Doc.ps. Additional documentation can be found on http://www.cs.utah.edu/~beazley/SWIG/swig.html The file RELEASE.notes contains some notes about this version. The file wrap.man contains information on how to run SWIG, including all of the command line options. 8. Examples ------------ The Examples directory of this distribution includes some SWIG example programs, including those from the documentation. This directory is, unfortunately, a little bare since SWIG is still new. However, I hope there is enough to get you going. The file Makefile.template shows how code can be compiled for all of the different languages supported by SWIG. This template works on most Unix systems although you might need to make a few modifications depending on where you have installed things. 9. Extending SWIG ------------------ The directory "user" contains files you can use to make your own extensions to SWIG--including the development of new language classes. See the user's guide and files in this directory for more information. 10. Bug Reports ---------------- Bug reports should be submitted to beazley@cs.utah.edu. I am committed to providing quality software and will make every attempt to fix bugs as soon as possible. However, SWIG is still in Beta release so don't expect it to be completely bug free. 11. Legal Stuff --------------- SWIG is free software. I hope that you find it useful. If so, you are free to do anything you like with it as long as you do two things. 1) Keep all of the copyright notices intact in any distributions of the software and 2) Don't sue me if it breaks. 12. Disclaimer ---------------- Ah yes, this is Beta release software. Hopefully it will work flawlessly, but I'm sure unseen bugs are hiding around. If you experience any problems, please let me know and I'll try to fix the problem as soon as possible. Just don't be surprised if there are a few quirks and rough edges at this point. 13. Special Thanks ------------------- I would like to acknowledge those who have contributed to SWIG and offered valuable feedback. Special thanks to : Kurtis Bleeker John Buckman Tim Germann Jean-Pierre Heber Brad Holian Chris Johnson Jeff Johnson Peter Lomdahl Steve Parker John Schmidt Peter-Pike Sloan Patrick Tullmann Larry Virden Simon Warfield Mike Weiblen Shujia Zhou Most of the development of SWIG has taken place in the Scientific Computing and Imaging Group at the University of Utah and the Theoretical Division at Los Alamos National Laboratory. Computing resources have been provided by the Department of Energy, National Science Foundation, and National Institutes of Health. If you find this package useful, I would like to hear about it. If you make a cool extension, share it with the rest of the world. Enjoy! Dave Beazley April 25, 1996