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
Backwards Compatibility
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
Supported C/C++ language features
Non-intrusive interface building
Hands off code generation
SWIG and freedom
2 Getting started on Windows
Installation on Windows
Windows Executable
Runtime Libraries
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 MinGW and MSYS
Building swig.exe using Cygwin
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
Default constructors
When constructor wrappers aren't created
Copy constructors
Member functions
Static members
Member functions and default arguments
Member data
Protection
Enums and constants
Friends
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
Dispatch function generation
Ambiguity in Overloading
Ambiguity resolution and renaming
Comments on overloading
Wrapping overloaded operators
Class extension
Templates
Namespaces
Exception specifiers
Pointers to Members
Smart pointers and operator->()
Using declarations and inheritance
Partial class definitions
A brief rant about const-correctness
Proxy classes
Construction of proxy classes
Resource management in proxies
Language specific details
Where to go for more information
6 Preprocessing
File inclusion
File imports
Conditional Compilation
Macro Expansion
SWIG Macros
C99 and GNU Extensions
Preprocessing and %{ ... %} blocks
Preprocessing and { ... }
7 Argument Handling
The typemaps.i library
Introduction
Input parameters
Output parameters
Input/Output parameters
Using different names
Applying constraints to input values
Simple constraint example
Constraint methods
Applying constraints to new datatypes
8 Typemaps
Introduction
Type conversion
Typemaps
Pattern matching
Reusing typemaps
What can be done with typemaps?
What can't be done with typemaps?
The rest of this chapter
Typemap specifications
Defining a typemap
Typemap scope
Copying a typemap
Deleting a typemap
Placement of typemaps
Pattern matching rules
Basic matching rules
Typedef reductions
Default typemaps
Multi-arguments typemaps
Code generation rules
Scope
Declaring new local variables
Special variables
Common typemap methods
"in" typemap
"typecheck" typemap
"out" typemap
"arginit" typemap
"default" typemap
"check" typemap
"argout" typemap
"freearg" typemap
"newfree" typemap
"memberin" typemap
"varin" typemap
"varout" typemap
Some typemap examples
Typemaps for arrays
Implementing constraints with typemaps
Multi-argument typemaps
The run-time type checker
Typemaps and overloading
More about
%apply
and
%clear
Reducing wrapper code size
Passing data between typemaps
Where to go for more information?
9 Customization Features
Exception handling with %exception
Handling exceptions in C code
Exception handling with longjmp()
Handling C++ exceptions
Defining different exception handlers
Using The SWIG exception library
Object ownership and %newobject
Features and the %feature directive
10 Contracts
The %contract directive
%contract and classes
Constant aggregation and %aggregate_check
Notes
11 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
12 Warning Messages
Introduction
Warning message suppression
Enabling additional warnings
Issuing a warning message
Commentary
Message output format
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
13 SWIG library
The %include directive and library search path
C Arrays and Pointers
cpointer.i
carrays.i
cmalloc.i
cdata.i
C String Handling
Default string handling
Passing binary data
Using %newobject to release memory
cstring.i
C++ Library
std_string.i
std_vector.i
Utility Libraries
exception.i
14 Working with Modules
The SWIG runtime code
Compiling Multiple SWIG modules
A word of caution about static libraries
References
15 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
16 SWIG and Guile
Meaning of "Module"
Using the SCM or GH Guile API
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
Representation of pointers as smobs
GH Smobs
SCM Smobs
Garbage Collection
Exception Handling
Procedure documentation
Procedures with setters
GOOPS Shadow Classes
Naming Issues
Linking
17 SWIG and Java
Overview
Preliminaries
Running SWIG
Additional Commandline Options
Getting the right header files
Compiling a dynamic module
Using your module
Dynamic linking problems
Compilation problems and compiling with C++
Building on Windows
Running SWIG from Visual Studio
Using NMAKE
A tour of basic C/C++ wrapping
Modules, packages and generated Java classes
Functions
Global variables
Constants
Enumerations
Pointers
Structures
C++ classes
C++ inheritance
Pointers, references, arrays and pass by value
Null pointers
C++ overloaded functions
C++ namespaces
C++ templates
C++ Smart Pointers
Further details on the generated Java classes
The intermediary JNI class
The intermediary JNI class pragmas
The Java module class
The Java module class pragmas
Java proxy classes
Memory management
Inheritance
Proxy classes and garbage collection
Type wrapper classes
Cross language polymorphism using directors (experimental)
Enabling directors
Director classes
Overhead and code bloat
Simple directors example
Common customization features
C/C++ helper functions
Class extension with %extend
Exception handling with %exception
Method access with %javamethodmodifiers
Tips and techniques
Input and output parameters using primitive pointers and references
Simple pointers
Wrapping C arrays with Java arrays
Unbounded C Arrays
Java typemaps
Default primitive type mappings
Sixty four bit JVMs
What is a typemap?
Typemaps for mapping C/C++ types to Java types
Java special variables
Typemaps for both C and C++ compilation
Java code typemaps
Director specific typemaps
Typemap Examples
Converting Java String arrays to char **
Expanding a Java object to multiple arguments
Using typemaps to return arguments
Adding Java downcasts to polymorphic return types
Adding an equals method to the Java classes
Void pointers and a common Java base class
Living with Java Directors
Odds and ends
JavaDoc comments
Functional interface without proxy classes
Using your own JNI functions
Performance concerns and hints
Examples
18 SWIG and Ocaml
Preliminaries
Running SWIG
Compiling the code
The camlp4 module
Using your module
Compilation problems and compiling with C++
The low-level Ocaml/C interface
The generated module
Enums
Arrays
Simple types of bounded arrays
Complex and unbounded arrays
Using an object
Example typemap for a function taking float * and int
C++ Classes
STL vector and string Example
C++ Class Example
Compiling the example
Sample Session
Director Classes
Director Introduction
Overriding Methods in Ocaml
Director Usage Example
Creating director objects
Typemaps for directors,
directorin, directorout, directorargout
directorin
typemap
directorout
typemap
directorargout
typemap
Exceptions
19 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
20 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...
21 SWIG and Python
Overview
Preliminaries
Running SWIG
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
A tour of basic C/C++ wrapping
Modules
Functions
Global variables
Constants and enums
Pointers
Structures
C++ classes
C++ inheritance
Pointers, references, values, and arrays
C++ overloaded functions
C++ operators
C++ namespaces
C++ templates
C++ Smart Pointers
Further details on the Python class interface
Proxy classes
Memory management
Python 2.2 and classic classes
Cross language polymorphism (experimental)
Enabling directors
Director classes
Ownership and object destruction
Exception unrolling
Overhead and code bloat
Typemaps
Miscellaneous
Common customization features
C/C++ helper functions
Adding additional Python code
Class extension with %extend
Exception handling with %exception
Tips and techniques
Input and output parameters
Simple pointers
Unbounded C Arrays
String handling
Arrays
String arrays
STL wrappers
Typemaps
What is a typemap?
Python typemaps
Typemap variables
Useful Python Functions
Typemap Examples
Converting Python list to a char **
Expanding a Python object into multiple arguments
Using typemaps to return arguments
Mapping Python tuples into small arrays
Mapping sequences to C arrays
Pointer handling
22 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++ Inheritance
C++ Overloaded Functions
C++ Operators
C++ namespaces
C++ templates
C++ Smart Pointers
Cross-Language Polymorphism
Exception Unrolling
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 a Ruby array to a char **
Collecting arguments in a hash
Pointer handling
Ruby Datatype Wrapping
Operator overloading
Example: STL Vector to Ruby Array
Advanced Topics
Creating Multi-Module Packages
Defining Aliases
Predicate Methods
Specifying Mixin Modules
Interacting with Ruby's Garbage Collector
23 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
A tour of basic C/C++ wrapping
Modules
Functions
Global variables
Constants and enums
Pointers
Structures
C++ classes
C++ inheritance
Pointers, references, values, and arrays
C++ overloaded functions
C++ operators
C++ namespaces
C++ templates
C++ Smart Pointers
Further details on the Tcl class interface
Proxy classes
Memory management
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
24 SWIG and Chicken
Preliminaries
Running SWIG in C mode
Running SWIG in C++ mode
Code Generation
Naming Conventions
Modules and Prefixes
Constants and Variables
Functions
TinyCLOS
Compilation
Linkage
Customized Interpreter
Typemaps
Pointers
Unsupported features
25 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
Iterating over Lists and Hashes
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
Configuration files
Runtime support
Standard library files
Examples and test cases
Documentation
Typemaps
Proxy classes
Guide to parse tree nodes