Path: usenet.cis.ufl.edu!usenet.eel.ufl.edu!news.mathworks.com!news.kei.com!news.texas.net!news1.best.com!sgigate.sgi.com!news.msfc.nasa.gov!news.larc.nasa.gov!lerc.nasa.gov!magnus.acs.ohio-state.edu!math.ohio-state.edu!uwm.edu!spool.mu.edu!news.sol.net!uniserve!van-bc!unixg.ubc.ca!nntp.cs.ubc.ca!psgrain!nntp.teleport.com!usenet From: beazley@sol.cs.utah.edu (David Beazley) Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc Subject: ANNOUNCE : SWIG 1.0 Beta Followup-To: comp.lang.perl.misc Date: 11 Apr 1996 03:37:35 GMT Organization: University of Utah Computer Science Department Lines: 426 Approved: merlyn@stonehenge.com (comp.lang.perl.announce) Message-ID: <4khupv$h33@nadine.teleport.com> NNTP-Posting-Host: julie.teleport.com X-Disclaimer: The "Approved" header verifies header information for article transmission and does not imply approval of content. Xref: usenet.cis.ufl.edu comp.lang.perl.announce:316 comp.lang.perl.misc:26631 April 9, 1996 Announcing SWIG 1.0 Beta ======================== I am pleased to announce the beta release of SWIG (Simplified Wrapper and Interface Generator) for Tcl/Tk, Perl, Python, and Guile. What is SWIG? ------------- SWIG is an easy-to-use tool that lets you add scripting language interfaces to programs written in C and C++. Most scripting languages can be extended with C and C++ functions. Unfortunately, doing so requires one to write special "wrapper" functions--a process that is usually tedious, error prone, and poorly documented. SWIG automates this process and frees you to work on the problem at hand instead of the grungy details of extending your favorite scripting language. Unlike many other approaches, SWIG is language independent and requires *little or no* modification to your existing C code. What does SWIG provide? ----------------------- SWIG provides the following functionality for Tcl, Perl4, Perl5, Python, and Guile: 1. Direct access to C/C++ functions. 2. Variable linkage (access to C/C++ global variables) 3. Constant creation. 4. Support for most of C's basic datatypes. 5. Type-checked manipulation of C/C++ pointers, including pointers to structs, classes and arrays. 6. Automatic documentation generation in ASCII, LaTeX, and HTML. *** You already know how to use SWIG *** ---------------------------------------- You can learn how to use SWIG in about 5 minutes because everything is done using ANSI C syntax. - Wrapper functions are created from ANSI C function prototypes. - Link to C variables by simply declaring them. - Create constants with #define and enum. SWIG also adds a small number of specialized directives to do things like include files, rename functions, etc... A simple example: ---------------- How hard is it to use SWIG? It's easy. Suppose you wanted to add the following variable and function to the "tclsh" shell : /* File : example.c */ double My_variable = 3.7; int fact(int n) { if (n <= 1) return 1; else return n*fact(n-1); } You would write a SWIG interface file that looks like the following (by convention these have a .i suffix): // File : example.i %{ /* Put header files and support code here */ %} %include tclsh.i extern double My_variable; extern int fact(int); SWIG is invoked with the "wrap" command. This produces a new file with a "_wrap.c" suffix. For our example, we can build a new version of tclsh and run it as follows : unix > wrap -tcl example.i unix > gcc example.c example_wrap.c -ltcl -lm -o my_tclsh unix > my_tclsh % fact 4 24 % puts $My_variable + 4 7.7 % You're done. You've just extended tclsh with a new function and variable. While we're at it, we can also build a Perl5 module : unix > wrap -perl5 -module Example example.i unix > gcc -c example.c example_wrap.c -I/usr/local/src/perl5.001m unix > ld -shared example.o example_wrap.o -o Example.so Since SWIG interface files are language independent, switching languages is trivial. Usually you can just change a few command line options and recompile the wrapper code. Type-checked pointers --------------------- One of SWIG's most powerful features is its support for type-checked C pointers. SWIG allows you to wrap almost any C function, even if it involves pointers to complex objects such as structs and classes. For example, we could wrap some of Tcl's C API with the following SWIG file : // tcl.i // Wrap Tcl's C interface %{ #include %} Tcl_Interp *Tcl_CreateInterp(void); void Tcl_DeleteInterp(Tcl_Interp *interp); int Tcl_Eval(Tcl_Interp *interp, char *script); int Tcl_EvalFile(Tcl_Interp *interp, char *file); This could, in turn be used to add Tcl support to other scripting languages. For example, we might turn this into a Python module as follows : unix > wrap -python -module tcl tcl.i unix > gcc -c tcl_wrap.c -I/usr/local/include/Py unix > ld -shared tcl_wrap.c -ltcl -lm -o tclmodule.so Our commands could then be used normally within a Python program as follows : unix > python Python 1.3 (Mar 26 1996) [GCC 2.7.0] Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam >>> import tcl >>> interp = tcl.Tcl_CreateInterp(); >>> tcl.Tcl_Eval(interp,"for {set i 0} {$i < 5} {incr i 1} {puts $i}"); 0 1 2 3 4 0 >>> SWIG pointers are type-checked at run-time. Violations result in a type-error exception in whatever scripting language is being used. Like C, functions accepting void* can accept any kind of pointer. The SWIG library and multiple files ----------------------------------- SWIG lets you build libraries and break interfaces into multiple files. Suppose that you have written a collection of independent SWIG interface files for various pieces of an application. You can easily combine all of these into a single file as follows : // File : package.i // Build a package out of multiple files %{ %} %include graphics.i %include network.i %include simulate.i %include files.i This file would combine all of the functions from graphics.i, network.i, simulate.i, and files.i into a single extension. SWIG comes with it's own library of useful functions and language specific extensions. For example, "%include wish.i" includes code to build a new wish application while "%include expect.i" would insert code needed to build an enhanced version of expect. The SWIG library is entirely composed of SWIG interface files that can be inserted into other interface files as needed. SWIG library files can be both language specific or language independent as appropriate. You can also build your own libraries for use in particular applications. Real applications involving SWIG -------------------------------- SWIG is primarily designed for researchers who would like to build interesting interfaces for their codes, but with minimal effort and hassle. Here are some current projects using SWIG : 1. The SPaSM molecular dynamics code at Los Alamos National Laboratory. SWIG is used to wrap about 250 functions and variables into a user-interface for use on the Connection Machine 5 and Cray T3D. 2. Defibrillation research at the University of Utah. John Schmidt has used SWIG to glue together a finite element solver, mesh generator, and visualization module into a single package controlled via a Tcl/Tk interface. Believe me, if John uses SWIG, you can too. 3. Peter-Pike Sloan at the University of Utah used SWIG to wrap the entire contents of the Open-GL library into Tcl---creating an interpreted Open-GL environment for use with an Open-GL Tk widget. This required about 5 minutes of work since SWIG was able to parse almost all of the Open-GL gl.h header file without modification. SWIG was also used to wrap most of the glu.h header file. The final package contained more than 650 constants and 380 C functions. ... and more users are starting to discover how easy it is to use SWIG their own applications. What else can you do with SWIG? ------------------------------- SWIG has a number of uses--some of which you might not expect. 1. Building interesting interfaces for existing applications. Since SWIG works with most C functions, you can usually build an interface without changing your code. If changes are required, it usually only involves main() (which sometimes needs to be renamed or removed). 2. Extremely rapid prototyping. Wrapping code is fast and easy. Adding functions and variables to your scripting language often only takes a matter of minutes and can usually be done by copying header files and making a few minor modifications. 3. Debugging. Have you ever considered using Tcl or Perl as a debugger? With SWIG you can build interfaces for code that might not even have an "interface" when finished. For example, I recently had to write a simple network server. To test it out, I wrapped all of its functions in Tcl and wrote scripts to create clients and test out various operations. When finished, I took away the SWIG interface and was left with standard C code that linked with other programs. 4. Providing an easy-to-use user-extension mechanism. Suppose you've got a big 100,000 line program involving a bunch of C++,C and Tcl/Tk and you'd like the user to be able to extend it with their own customizations. Why not use SWIG? A SWIG interface file could be used to add user extensions as needed and the user doesn't need to worry about all of the nasty underlying details of how you've actually built the interface. 5. Building modules. SWIG can certainly be used to build Tcl, Perl, and Python modules. This wasn't my original intent, but there's nothing stopping you from using SWIG as a module builder. Can't find a module with the functionality you want? Build it yourself with SWIG. 6. Developing language-independent applications. Each scripting language is better at different things. With SWIG you can choose the language most appropriate for the job. Since SWIG doesn't require code modifications, you can even use it to evaluate different interface languages without risk. You could even let the end-user choose the one they want to use. 7. Combining applications. With SWIG you can glue together different programs to form interesting applications. For example, you could wrap a simulation package and the C API to Matlab and use the two together to make an interactive data-analysis and visualization tool. Does SWIG work with other extensions? ------------------------------------- SWIG is not a language extension. It works all of its magic through the standard C API of the target scripting language. Therefore, you should be able to use SWIG with other extentions as needed. Usually this can be done by inserting a call to SWIG's initialization function inside the initialization function used by the third party extention. With dynamic loading, it is even easier. Extending SWIG -------------- SWIG is implemented as a collection of C++ classes. You can support a new target language by making a new class. Or if you desire, you can make customizations one of the existing language classes. The SWIG distribution comes with a template file containing everything you need to customize SWIG to your liking. Other Features of SWIG ---------------------- - Automatic documentation generation in ASCII, LaTeX, HTML. SWIG can turn C/C++ comments into documentation describing your interface. - Error messages. SWIG generates sensible error messages (including line numbers and files). Mistakes in SWIG interface files are pretty easy to track down. - Performance. SWIG is written entirely in C++ and is fast. Wrapping the Open-GL library takes about 1 second on an SGI Indy. Installation Requirements ------------------------- 1. A C++ compiler 2. bison or yacc 3. Tcl/Tk, Perl, Python, or Guile (otherwise SWIG is pretty useless). Supported Systems ----------------- SWIG works on virtually all Unix systems. I've tested it on the following systems : SunOS 4.1.3 Solaris Irix 5.x,6.x HPUX Linux MachTen Target Languages ---------------- The following target languages are supported : Tcl 7.3, Tk 3.6 (and all newer versions). Perl4 Perl5 Guile-iii Python 1.3 Where can I get SWIG? --------------------- SWIG is available at the following locations : http://www.cs.utah.edu/~beazley/SWIG or anonymous-ftp at ftp://ftp.cs.utah.edu/pub/beazley/SWIG The distribution includes a user manual and some examples. SWIG is free software. You may use it in any manner provided you retain its original copyright notices. SWIG Resources (and mailing list) --------------------------------- If you would like to learn more about SWIG, you can check out the SWIG homepage listed above. You can also subscribe to the SWIG mailing list by sending a message "subscribe swig" to Majordomo@cs.utah.edu. Changes since the last release ------------------------------ SWIG 1.0b1 represents a significant upgrade of SWIG 0.1a. New features include : - Type-checked pointers - Python 1.3 support - #define and enums create constants. - Support for const and struct keywords - Better multiple file support - Small bugs fixes to many parts of the code - Improved portability of SWIG source Try SWIG risk free! ------------------- Again, SWIG requires virtually no modifications to your C programs. You can start using it immediately. If you don't like it, just blow away the SWIG interface file and go back to your original C program. It's that easy. Questions about SWIG may be addressed to myself at the address below or to the swig mailing list at swig@cs.utah.edu. Cheers, Dave ---------------------------------------------------------------- Dave Beazley Department of Computer Science University of Utah Salt Lake City, Utah 84112 beazley@cs.utah.edu http://www.cs.utah.edu/~beazley ----------------------------------------------------------------