SWIG Users Manual

1 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

2 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

3 Getting started on Windows

• Installation on Windows
  • Windows Executable
• SWIG Windows Examples
  • Instructions for using the Examples with Visual Studio
    • Python
    • TCL
    • Perl
    • Java
    • Ruby
    • C#
  • 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

4 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

5 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()

6 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

7 Preprocessing

• File inclusion
• File imports
• Conditional Compilation
• Macro Expansion
• SWIG Macros
• C99 and GNU Extensions
• Preprocessing and %{ ... %} blocks
• Preprocessing and { ... }
• Viewing preprocessor output

8 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

9 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

10 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
  • "throws" 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?

11 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

12 Contracts

• The %contract directive
• %contract and classes
• Constant aggregation and %aggregate_check
• Notes

13 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

14 Warning Messages

• Introduction
• Warning message suppression
• Enabling additional warnings
• Issuing a warning message
• Commentary
• Warnings as errors
• 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

15 Working with Modules

• The SWIG runtime code
• Compiling Multiple SWIG modules
• A word of caution about static libraries
• References
• Reducing the wrapper file size

16 SWIG and C#

17 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
  • Shared library
  • Static binary
• Typemaps
• Pointers
• Unsupported features

18 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

19 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
    • Anonymous enums
    • Typesafe enums
    • Proper Java enums
    • Type unsafe enums
    • Simple enums
  • 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
  • Enum classes
    • Typesafe enum classes
    • Proper Java enum classes
    • Type unsafe enum 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 and %javaexception
  • 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 typemap attributes
  • Java special variables
  • Typemaps for both C and C++ compilation
  • Java code typemaps
  • Director specific typemaps
• Typemap Examples
  • Simpler Java enums for enums without initializers
  • Handling C++ exception specifications as Java exceptions
  • NaN Exception - exception handling for a particular type
  • 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

20 SWIG and Modula-3

• Overview
• Conception
  • Interfaces to C libraries
  • Interfaces to C++ libraries
  • No plan?
• Preliminaries
  • Compilers
  • Additional Commandline Options
• Modula-3 typemaps
  • Inputs and outputs
  • Subranges, Enumerations, Sets
  • Objects
  • Imports
  • Exceptions
  • Pragmas
  • Example
  • Remarks

21 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

22 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
  • Structure and class wrappers
  • Object Ownership
  • Nested Objects
  • Shadow Functions
  • Inheritance

23 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...

24 SWIG and Pike

• Preliminaries
  • Running SWIG
  • Getting the right header files
  • Using your module
• Basic C/C++ Mapping
  • Modules
  • Functions
  • Global variables
  • Constants and enumerated types
  • Constructors and Destructors
  • Static Members

25 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

26 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

27 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

28 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

29 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