SWIG Users Manual
0 Preface
Introduction
Special Introduction for Version 1.3
SWIG Versions
SWIG resources
Prerequisites
Organization of this manual
How to avoid reading the manual
Credits
Bug reports
1 Introduction
What is SWIG?
Why use SWIG?
A SWIG example
SWIG interface file
The swig command
Building a Perl5 module
Building a Python module
Shortcuts
Building libraries and modules
C syntax, but not a C compiler
Non-intrusive interface building
Hands off code generation
2 Getting started on Windows
Installation on Windows
Windows Executable
SWIG Windows Examples
Instructions for using the Examples with Visual C++
Python
TCL
Perl
Java
Ruby
Instructions for using the Examples with other compilers
SWIG on Cygwin and Mingw
Building swig.exe on Windows
Building swig.exe using Cygwin and Mingw
Building swig.exe alternatives
Running the examples on Windows using Cygwin
3 Scripting Languages
The two language view of the world
How does a scripting language talk to C?
Wrapper functions
Variable linking
Constants
Structures and classes
Shadow classes
Building scripting language extensions
Shared libraries and dynamic loading
Linking with shared libraries
Static linking
4 SWIG Basics
Running SWIG
Input format
SWIG Output
Comments
C Preprocessor
SWIG Directives
Parser Limitations
Wrapping Simple C Declarations
Basic Type Handling
Global Variables
Constants
A brief word about
const
A cautionary tale of
char *
Pointers and complex objects
Simple pointers
Run time pointer type checking
Derived types, structs, and classes
Undefined datatypes
Typedef
Other Practicalities
Passing structures by value
Return by value
Linking to structure variables
Linking to
char *
Arrays
Creating read-only variables
Renaming and ignoring declarations
Default/optional arguments
Pointers to functions and callbacks
Structures and unions
Typedef and structures
Character strings and structures
Array members
Structure data members
C constructors and destructors
Adding member functions to C structures
Nested structures
Other things to note about structure wrapping
Code Insertion
The output of SWIG
Code insertion blocks
Inlined code blocks
Initialization blocks
An Interface Building Strategy
Preparing a C program for SWIG
The SWIG interface file
Why use separate interface files?
Getting the right header files
What to do with main()
5 SWIG and C++
Comments on C++ Wrapping
Approach
Supported C++ features
Command line options and compilation
Simple C++ wrapping
Constructors and destructors
Copy constructors
Member functions
Static members
Member functions and default arguments
Member data
Protection
Enums and constants
References and pointers
Pass and return by value
Inheritance
A brief discussion of multiple inheritance, pointers, and type checking
Renaming
Wrapping Overloaded Functions and Methods
Wrapping overloaded operators
Class extension
Templates
Namespaces
Pointers to Members
Partial class definitions
A brief rant about const-correctness
Proxy classes
Where to go for more information
6 Preprocessing
File inclusion
File imports
Conditional Compilation
Macro Expansion
SWIG Macros
C99 Extensions
Preprocessing and %{ ... %} blocks
Preprocessing and { ... }
7 Types and Typemaps
Introduction
The Problem
Typemaps
Managing input and output parameters
Input parameters
Output parameters
Input/Output parameters
Using different names
Array handling
Applying constraints to input values
Simple constraint example
Constraint methods
Applying constraints to new datatypes
Writing new typemaps
The SWIG type system
What is a typemap?
Creating a new typemap
Deleting a typemap
Copying a typemap
Typemap matching rules
Common typemap methods
Writing typemap code
Local scope
Creating local variables
Special variables
Typemap Parameters
Typemaps for arrays
Implementing constraints with typemaps
Multi-argument typemaps
The default typemaps
The run-time type checker
More about
%apply
and
%clear
Reducing wrapper code size
Typemaps and C++
Where to go for more information?
8 Customization Features
Exception handling with %exception
Handling exceptions in C code
Exception handling with longjmp()
Handling C++ exceptions
Defining different exception handlers
Applying exception handlers to specific datatypes.
Using The SWIG exception library
Object ownership and %newobject
Features and the %feature directive
9 Variable Length Arguments
Introduction
The Problem
Default varargs support
Argument replacement using %varargs
Varargs and typemaps
Varargs wrapping with libffi
Wrapping of va_list
C++ Issues
Discussion
10 Warning Messages
Introduction
Warning message suppression
Enabling additional warnings
Issuing a warning message
Commentary
Warning number reference
Deprecated features (100-199)
Preprocessor (200-299)
C/C++ Parser (300-399)
Types and typemaps (400-499)
Code generation (500-599)
Language module specific (800-899)
User defined (900-999)
History
11 SWIG library
The %include directive and library search path
C Arrays and Pointers
cpointer.i
carrays.i
cmalloc.i
cdata.i
C++ Library
std_string.i
std_vector.i
12 Advanced Topics
Creating multi-module packages
Runtime support (and potential problems)
Why doesn't C++ inheritance work between modules?
The SWIG runtime library
A few dynamic loading gotchas
Dynamic Loading of C++ modules
Inside the SWIG type-checker
Type equivalence
Type casting
Why a name based approach?
Performance of the type-checker
13 SWIG and Guile
Meaning of "Module"
Linkage
Simple Linkage
Passive Linkage
Native Guile Module Linkage
Old Auto-Loading Guile Module Linkage
Hobbit4D Linkage
General Remarks on Multiple SWIG Modules
Underscore Folding
Typemaps
Smobs
Exception Handling
Procedure documentation
Procedures with setters
14 SWIG and Java
Preliminaries
Running SWIG
Additional Commandline Options
Getting the right header files
Compiling a dynamic module
Using your module
Compilation problems and compiling with C++
Building Java Extensions under Windows
Running SWIG from Developer Studio
Using NMAKE
The low-level Java/C interface
Modules and the module class
Functions
Variable Linking
Enums
Constants
Pointers
Structures
C++ Classes
Java proxy classes
A simple example
Why write proxy classes in Java?
Automated proxy class generation
Compiling modules with proxy classes
Where to go for more information
Examples
Exception handling
Remapping C datatypes with typemaps
Default type mapping
What is a typemap?
Java typemaps
Typemap variables
Typemaps for C and C++
Name based type conversion
Converting Java String arrays to char **
Using typemaps to return arguments
Accessing array structure members
Pointer handling
The gory details of proxy classes
A simple proxy class
Generated class
The this pointer
Object ownership
Constructors and destructors
Member data
Proxy functions
Proxy class pointer handling
Methods that return new objects
Global variables and functions
Nested objects
Inheritance and proxy classes
Proxy classes and garbage collection
Performance concerns and hints
Java pragmas
Deprecated pragmas
Pragma uses
Derive C++ from Java and visa-versa
JavaDoc and the shadowcode pragma
Tips for using the shadow pragmas
Dynamic linking problems
Using your own JNI methods
Known bugs
15 SWIG and Perl5
Overview
Preliminaries
Getting the right header files
Compiling a dynamic module
Building a dynamic module with MakeMaker
Building a static version of Perl
Using the module
Compilation problems and compiling with C++
Compiling for 64-bit platforms
Building Perl Extensions under Windows
Running SWIG from Developer Studio
Using other compilers
The low-level interface
Functions
Global variables
Constants
Pointers
Structures
C++ classes
C++ classes and type-checking
C++ overloaded functions
Operators
Modules and packages
Input and output parameters
Exception handling
Remapping datatypes with typemaps
A simple typemap example
Perl5 typemaps
Typemap variables
Useful functions
Typemap Examples
Converting a Perl5 array to a char **
Return values
Returning values from arguments
Accessing array structure members
Turning Perl references into C pointers
Pointer handling
Proxy classes
Preliminaries
Object Ownership
Nested Objects
Shadow Functions
Inheritance
16 SWIG and PHP4
Preliminaries
Building PHP4 Extensions
Building a loadable extension
Basic PHP4 interface
Functions
Global Variables
Pointers
Structures and C++ classes
Constants
Shadow classes
Constructors and Destructers
Static Member Variables
PHP4 Pragmas
Building extensions into php
To be furthered...
17 SWIG and Python
Overview
Preliminaries
Getting the right header files
Compiling a dynamic module
Using distutils
Static linking
Using your module
Compilation of C++ extensions
Compiling for 64-bit platforms
Building Python Extensions under Windows
The low-level procedural interface
Modules
Functions
Variable Linking
Constants
Pointers
Structures
C++ classes
C++ classes and type-checking
C++ overloaded functions
Operators
Input and output parameters
Simple exception handling
Typemaps
What is a typemap?
Python typemaps
Typemap variables
Useful Functions
Typemap Examples
Converting Python list to a char **
Expanding a Python object to multiple arguments
Using typemaps to return arguments
Mapping Python tuples into small arrays
Mapping sequences to C arrays
Accessing array structure members
Pointer handling
Other odds and ends
Adding native Python functions to a SWIG module
Python shadow classes
A simple example
Why shadow classes?
Automatic shadow class generation
Compiling modules with shadow classes
Shadow classes and type-checking
A preview
The gory details of shadow classes
A simple shadow class
Module names
Two classes
The this pointer
Object ownership
Constructors and Destructors
Member data
Printing
Shadow Functions
Nested objects
Inheritance and shadow classes
Methods that return new objects
Performance concerns and hints
18 SWIG and Ruby
Preliminaries
Running SWIG
Getting the right header files
Compiling a dynamic module
Using your module
Static linking
Compilation of C++ extensions
Building Ruby Extensions under Windows 95/NT
Running SWIG from Developer Studio
The Ruby-to-C/C++ Mapping
Modules
Functions
Variable Linking
Constants
Pointers
Structures
C++ classes
C++ classes and type-checking
C++ overloaded functions
Operators
Input and output parameters
Simple exception handling
Typemaps
What is a typemap?
Ruby typemaps
Typemap variables
Useful Functions
C Datatypes to Ruby Objects
Ruby Objects to C Datatypes
Macros for VALUE
Exceptions
Iterators
Typemap Examples
Converting Ruby list to a char **
Pointer handling
Ruby Datatype Wrapping
Adding native Ruby functions to a SWIG module
Operator overloading
An example (putting everything together)
Expanding the example
Advanced Topics
Creating Multi-Module Packages
Defining Aliases
Predicate Methods
Interacting with Ruby's Garbage Collector
19 SWIG and Tcl
Preliminaries
Getting the right header files
Compiling a dynamic module
Static linking
Using your module
Compilation of C++ extensions
Compiling for 64-bit platforms
Setting a package prefix
Using namespaces
Building Tcl/Tk Extensions under Windows 95/NT
Running SWIG from Developer Studio
Using NMAKE
Primitive Tcl Interface
Functions
Global variables
Constants
Pointers
Structures
C++ Classes
The object-based interface
Creating new objects
Invoking member functions
Deleting objects
Accessing member data
Changing member data
Managing Object Ownership
Relationship with pointers
Input and output parameters
Exception handling
Typemaps
What is a typemap?
Tcl typemaps
Typemap variables
Converting a Tcl list to a char **
Returning values in arguments
Useful functions
Standard typemaps
Pointer handling
Turning a SWIG module into a Tcl Package.
Building new kinds of Tcl interfaces (in Tcl)
Shadow classes
20 Extending SWIG
Introduction
Prerequisites
The Big Picture
Execution Model
Preprocessing
Parsing
Parse Trees
Attribute namespaces
Symbol Tables
The %feature directive
Code Generation
SWIG and XML
Primitive Data Structures
Strings
Hashes
Lists
Common operations
I/O
Navigating and manipulating parse trees
Working with attributes
Type system
String encoding of types
Type construction
Type tests
Typedef and inheritance
Lvalues
Output functions
Parameters
Writing a Language Module
Execution model
Starting out
Command line options
Configuration and preprocessing
Entry point to code generation
Module I/O and wrapper skeleton
Low-level code generators
Typemaps
Proxy classes
Guide to parse tree nodes