Table of Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 SWIG resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 What’s new? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Bug reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 SWIG is free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

What is SWIG? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Life before SWIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Life after SWIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 The SWIG package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 A SWIG example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 C syntax, but not a C compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Non-intrusive interface building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Hands off code generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Event driven C programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Automatic documentation generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 SWIG for Windows and Macintosh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Scripting Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

The two language view of the world. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 How does a scripting language talk to C?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Building scripting language extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Shared libraries and dynamic loading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

SWIG Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Running SWIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Simple C functions, variables, and constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Pointers and complex objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Getting down to business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Structures, unions, and object oriented C programming. . . . . . . . . . . . . . . . . . . . 42 C++ support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Objective-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Conditional compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Code Insertion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 A general interface building strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Version 1.1, June 24, 1997

Multiple files and the SWIG library . . . . . . . . . . . . . . . . . . . . . . . . . . 68

The %include directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 The %extern directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 The %import directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Including files on the command line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 The SWIG library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Library example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Creating Library Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Working with library files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Static initialization of multiple modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 More about the SWIG library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Documentation System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 How it works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Choosing a documentation format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Function usage and argument names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Titles, sections, and subsections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Formatting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Adding Additional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Disabling all documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 ASCII Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 HTML Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 LaTeX Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 C++ Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 The Final Word? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Pointers, Constraints, and Typemaps . . . . . . . . . . . . . . . . . . . . . . . . . 90

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 The SWIG Pointer Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Introduction to typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Managing input and output parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Applying constraints to input values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Writing new typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Common typemap methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Writing typemap code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Typemaps for handling arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Typemaps and the SWIG Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Implementing constraints with typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Typemap examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 How to break everything with a typemap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Typemaps and the future. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Version 1.1, June 24, 1997

Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

The %except directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Handling exceptions in C code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Exception handling with longjmp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Handling C++ exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Defining different exception handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Using The SWIG exception library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Debugging and other interesting uses for %except. . . . . . . . . . . . . . . . . . . . . . . 114 More Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

SWIG and Perl5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Building Perl Extensions under Windows 95/NT. . . . . . . . . . . . . . . . . . . . . . . . 118 Modules, packages, and classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Basic Perl interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 A simple Perl example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Accessing arrays and other strange objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Implementing methods in Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Shadow classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Getting serious . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Wrapping C libraries and other packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Building a Perl5 interface to MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Handling output values (the easy way) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Remapping datatypes with typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 The gory details on shadow classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Where to go from here? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

SWIG and Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Building Python Extensions under Windows 95/NT . . . . . . . . . . . . . . . . . . . . . 162 The low-level Python/C interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Python shadow classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 About the Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Solving a simple heat-equation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Wrapping a C library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Putting it all together. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Remapping C datatypes with typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Implementing C callback functions in Python . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Other odds and ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 The gory details of shadow classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Version 1.1, June 24, 1997

SWIG and Tcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Building Tcl/Tk Extensions under Windows 95/NT . . . . . . . . . . . . . . . . . . . . . 218 Basic Tcl Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 The object oriented interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 About the examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Binary trees in Tcl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Building C/C++ data structures with Tk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Accessing arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Building a simple OpenGL module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Typemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Configuration management with SWIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Building new kinds of Tcl interfaces (in Tcl) . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 Extending the Tcl Netscape Plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Tcl8.0 features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Creating multi-module packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Dynamic Loading of C++ modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Inside the SWIG type-checker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Extending SWIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Compiling a SWIG extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 SWIG output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 The Language class (simple version) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 A tour of SWIG datatypes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Typemaps (from C). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 File management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Naming Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Code Generation Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Writing a Real Language Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 C++ Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 Documentation Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 The Future of SWIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Version 1.1, June 24, 1997

Preface

Introduction

SWIG is a tool for solving problems.

More specifically, SWIG is a simple tool for building interactive C, C++, or Objective-C programs with common scripting languages such as Tcl, Perl, and Python. Of course, more importantly, SWIG is a tool for making C programming more enjoyable and promoting laziness (an essential feature). SWIG is not part of an overgrown software engineering project, an attempt to build some sort of monolithic programming environment, or an attempt to force everyone to rewrite all of their code (ie. code reuse). In fact, none of these things have ever been a priority.

SWIG was originally developed in the Theoretical Physics Division at Los Alamos National Laboratory for building interfaces to large materials science research simulations being run on the Connection Machine 5 supercomputer. In this environment, we were faced with the problems of working with huge amounts of data, complicated machines, and constantly changing code. As scientists, we needed a mechanism for building interactive programs that was extremely easy to use, could keep pace with code that was constantly changing, and didn’t get in the way of the real problems that were being solved. Mainly, we just wanted to “cut the crap” and work on the real problems at hand.

While SWIG was originally developed for scientific applications, it has become a general purpose tool that is being used in an increasing variety of other computing applications--in fact almost anything where C programming is involved. Some of the application areas that I am aware of include scientific applications, visualization, databases, semiconductor CAD, remote sensing and distributed objects. Development has been pragmatic in nature--features have been added to address interesting problems as they arise. Most of the really cool stuff has been contributed or suggested by SWIG’s users. There has never really been a “grand” design to SWIG other than the goal of creating a practical programming tool that could be used in other applications.

SWIG resources

The official location of SWIG related material is

http://www.cs.utah.edu/~beazley/SWIG

This site contains the latest version of the software, users guide, and information regarding bugs, installation problems, and implementation tricks. The latest version of the software and related files are also available via anonymous ftp at

ftp://ftp.cs.utah.edu/pub/beazley/SWIG

You can also subscribe to the SWIG mailing list by sending a message with the text “subscribe swig” to

Version 1.1, June 24, 1997