SWIG (Simplified Wrapper and Interface Generator) Version 1.1 Beta 5 (patch 1) Copyright (C) 1995-1997 University of Utah and the Regents of the University of California March 16, 1997 *** DISCLAIMER : This is beta release software. There are still a few glitches that need to be worked out and I'm in the process of updating the documentation. See the file 'NEW' for recent additions. Note : Full documentation is not yet distributed with this release. SWIG documentation (for version 1.0) can be obtained at ftp://ftp.cs.utah.edu/pub/beazley/SWIG. 1. Introduction --------------- SWIG is a compiler that makes it easy to integrate C and C++ code with scripting languages including Perl, Tcl, and Python. In a nutshell, you specify a bunch of ANSI C/C++ declarations and it generates an interface to your favorite scripting language. SWIG is almost entirely the product of users who have used the system and suggested new idea. Without this support, SWIG would be not be nearly as fun to use as it is now. Many thanks! 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) Tcl8.0, Tk8.0 (Highly experimental) Python1.3 (or newer) Perl5 Perl4 Guile [incr Tcl] If you don't have any of these, SWIG will still compile, but it won't be particularly useful. Note : it is not necessary to have all of these languages installed to use SWIG (although obviously its full power will not be realized otherwise). 3. Installation (Unix) ------------------------ 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 (if you are going to rebuild the parser) To compile and install SWIG, type the following : ./configure make make install The configuration script will attempt to locate various packages on your machine, including Tcl, Perl5, and Python. 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. See the Examples section below for more details. If you are paranoid, you can type 'make test' to run a series of tests before running '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,TCL8,PYTHON,PERL5,PERL4,GUILE} 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. 4. Site specific installation ------------------------------- While not required for compiling SWIG, the configuration script looks for various packages in order to create a makefile for compiling the examples. This makefile is also installed with the SWIG package. The following configuration options can be used to set the location of various packages. --with-tcl=pathname - Set root directory of Tcl installation. SWIG will use $pathname/include and $pathname/lib. --with-tclincl=pathname - Set exact location of Tcl include files --with-tcllib=pathname - Set exact location of Tcl library files --with-itcl=pathname - Same as above but for [incr Tcl] --with-itclincl=pathname - Location of [incr Tcl] include files --with-itcllib=pathname - Location of [incr Tcl] libraries --with-py=pathname - Set package location of Python. This is usually something like /usr/local. configure will attempt to locate the appropriate include and library files. --with-pyincl=pathname - Set location of Python include files (for example, /usr/local/include) --with-pylib=pathname - Set location of Python library files (for example, /usr/local/lib) --with-perl5=executable - Specify your perl5 executable. SWIG will figure out where files are by running this version of Perl and grabbing its configuration data. Other options : --without-yacc - Try to compile SWIG using a pregenerated YACC file generated by Berkeley YACC (byacc). Only recommended if you get compiler errors when trying to compile parser.y or parser.cxx. Changing the C++ compiler: By default, SWIG will look for g++. You can change the C++ compile as follows : env CXX=CC configure --prefix=/usr/local ... etc... or setenv CXX=CC ./configure ... etc ... SWIG has been successfully compiled and tested under g++, the SGI C++ compiler, and the Sun C++ compiler. 5. Testing ----------- The SWIG parser and language modules can be tested by typing 'make test'. Be forewarned, this runs a huge battery of tests on all of SWIG's language modules and documentation methods. The tests may take 5-10 minutes to run, but a report of errors will be written to 'test.log'. If this exists, it will contain error messages for failed tests. If the file is missing, it means all tests were successful. The testing process requires approximately 20-30 Mbytes of disk space. After testing, you may wish to type 'make testclean' which will return the testing directory to its original state. 6. Installation for Windows 95 and NT ------------------------------------- The Win directory contains makefiles for Microsoft Visual C++ 4.x. See the README file in the Win directory for specific build instructions. Many thanks to Kevin Butler (butler@cs.byu.edu) for supplying these Makefiles. 7. Installation for Macintosh ----------------------------- The Mac directory contains information about building SWIG on the Macintosh. A project file for Metrowerks Code Warrior 10 is included in bin-hex format. The Macintosh version of SWIG is *highly* experimental and has not been fully tested yet. 8. Examples ------------ The 'Examples' directory contains examples for all of the supported scripting languages. All of the examples rely on the file 'Makefile.template' located in the top-level directory. This makefile is created by 'configure', but the configuration process is not foolproof. To check this Makefile type make testbuild This will attempt to build various kinds of extensions and report its success or failure. If this fails, you may need to edit the file 'Makefile.template' by hand. This usually isn't difficult--just follow the instructions contained within the file. Once the 'make testbuild' works for the language you are interested in using, you should be able to build the examples. The examples will not compile properly if you have not installed SWIG. If you would like to try the examples before installation, set the SWIG_LIB environment variable as follows : setenv SWIG_LIB ${pathname}/SWIG1.1b5/swig_lib Where ${pathname} the location of the SWIG source. *** NOTE *** If you are replacing an older version of SWIG with a new one, the examples will not compile correctly unless you set the above environment variable or do a 'make install' first. 9. 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. 10. 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 - Windows 95 - MacOS System 7.5.3 SWIG development has primarily taken place on Linux, Solaris 2.5, Irix 5.3, and MkLinux. I've tested most of the examples on these platforms. I have also tested SWIG under Win95 and MacOS, but this is still somewhat experimental. 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. I answer all e-mail that I receive. However, occasionally I receive messages with bad return addresses and can't respond. If you don't hear back from me within a few days, try sending a message to 'swig@cs.utah.edu' or posting a message on comp.lang.tcl, comp.lang.python, or comp.lang.perl. 11. Documentation ----------------- Note : documentation for SWIG 1.1 is incomplete, but will be completed by the time 1.1 final goes out the door. A postscript version of the user manual is in the Doc directory. At last count, the user manual was getting rather large (over 100 pages), but don't let this scare you. SWIG is easy enough to use that you can probably start using it by only looking at a simple example. However, at some point you will probably want to know more so I hope that the manual will come in useful. 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.) 12. Incompatibilities --------------------- This release should be mostly compatible with SWIG 1.0 (Final). However, the SWIG documentation system has been completely rewritten and the C API has been changed greatly. It is unlikely that any custom SWIG language modules written in C++ for 1.0 will work with 1.1. While porting to 1.1 is not that difficult, there are a number of important changes. See the file 'Doc/Porting' for a list of changes to the C++ API and how to convert an older SWIG module to work with 1.1. 13. 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. However, I can only fix bugs if I know about them. 14. Legal Stuff --------------- SWIG is completely free. You can do whatever you want with it (including distribution), provided that you follow these rules, 1) Keep all of the copyright notices intact, 2) don't claim that you wrote it, and 3) Don't sue anyone if it breaks. Otherwise, have fun. 15. 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. 16. Acknowledgements --------------------- SWIG would not be possible without the contributions of people who tried out the beta versions and offered feedback and bug reports. While there are far too many people to list at point, I'd like to especially acknowledge the following individuals and organizations for supporting SWIG and making major contributions : David Ascher, Erik Bierwagen, Kurtis Bleeker, John Buckman, Kevin Butler, David Fletcher, Mark Harrison, Brad Holian, Gary Holt, Chris Johnson, Peter Lomdahl, Mark Lutz, Chris Meyers, Paul Saxe, John Schmidt, Tom Schwaller, Peter-Pike Sloan, Patrick Tullmann, Larry Virden, Tser-Yuan Yang, Shujia Zhou. and Los Alamos National Laboratory Lawrence Livermore National Laboratory Cornell Theory Center University of Utah The Scientific Computing and Imaging Group (University of Utah) (My apologies to anyone I missed...) If you find SWIG to be useful, I'd like to know about it. Enjoy! Dave Beazley Department of Computer Science University of Utah Salt Lake City, Utah 84112 beazley@cs.utah.edu March 12, 1997