SWIG-2.0 Documentation

Table of ContentsSWIG-2.0 Documentation..................................................................................................................................................................1

Sections...................................................................................................................................................................................1SWIG Core Documentation............................................................................................................................................1Language Module Documentation..................................................................................................................................1Developer Documentation...............................................................................................................................................1

1 Preface...............................................................................................................................................................................................21.1 Introduction.......................................................................................................................................................................21.2 SWIG Versions.................................................................................................................................................................21.3 SWIG License...................................................................................................................................................................21.4 SWIG resources................................................................................................................................................................21.5 Prerequisites......................................................................................................................................................................31.6 Organization of this manual..............................................................................................................................................31.7 How to avoid reading the manual.....................................................................................................................................31.8 Backwards compatibility..................................................................................................................................................31.9 Release notes....................................................................................................................................................................41.10 Credits.............................................................................................................................................................................41.11 Bug reports......................................................................................................................................................................41.12 Installation......................................................................................................................................................................4

1.12.1 Windows installation............................................................................................................................................41.12.2 Unix installation...................................................................................................................................................41.12.3 Macintosh OS X installation................................................................................................................................51.12.4 Testing..................................................................................................................................................................51.12.5 Examples..............................................................................................................................................................6

2 Introduction......................................................................................................................................................................................72.1 What is SWIG?.................................................................................................................................................................72.2 Why use SWIG?...............................................................................................................................................................72.3 A SWIG example..............................................................................................................................................................8

2.3.1 SWIG interface file.................................................................................................................................................82.3.2 The swig command.................................................................................................................................................92.3.3 Building a Perl5 module.........................................................................................................................................92.3.4 Building a Python module......................................................................................................................................92.3.5 Shortcuts...............................................................................................................................................................10

2.4 Supported C/C++ language features...............................................................................................................................102.5 Non-intrusive interface building.....................................................................................................................................112.6 Incorporating SWIG into a build system........................................................................................................................112.7 Hands off code generation..............................................................................................................................................112.8 SWIG and freedom.........................................................................................................................................................12

3 Getting started on Windows..........................................................................................................................................................133.1 Installation on Windows.................................................................................................................................................13

3.1.1 Windows Executable............................................................................................................................................133.2 SWIG Windows Examples.............................................................................................................................................13

3.2.1 Instructions for using the Examples with Visual Studio......................................................................................133.2.1.1 C#...............................................................................................................................................................143.2.1.2 Java.............................................................................................................................................................143.2.1.3 Perl.............................................................................................................................................................143.2.1.4 Python.........................................................................................................................................................143.2.1.5 TCL............................................................................................................................................................143.2.1.6 R.................................................................................................................................................................143.2.1.7 Ruby...........................................................................................................................................................15

3.2.2 Instructions for using the Examples with other compilers...................................................................................153.3 SWIG on Cygwin and MinGW......................................................................................................................................15

SWIG-2.0 Documentation

i

Table of Contents3 Getting started on Windows

3.3.1 Building swig.exe on Windows............................................................................................................................153.3.1.1 Building swig.exe using MinGW and MSYS............................................................................................153.3.1.2 Building swig.exe using Cygwin...............................................................................................................163.3.1.3 Building swig.exe alternatives...................................................................................................................16

3.3.2 Running the examples on Windows using Cygwin..............................................................................................163.4 Microsoft extensions and other Windows quirks...........................................................................................................16

4 Scripting Languages......................................................................................................................................................................184.1 The two language view of the world..............................................................................................................................184.2 How does a scripting language talk to C?......................................................................................................................18

4.2.1 Wrapper functions................................................................................................................................................194.2.2 Variable linking....................................................................................................................................................194.2.3 Constants..............................................................................................................................................................204.2.4 Structures and classes...........................................................................................................................................204.2.5 Proxy classes........................................................................................................................................................21

4.3 Building scripting language extensions..........................................................................................................................214.3.1 Shared libraries and dynamic loading..................................................................................................................214.3.2 Linking with shared libraries................................................................................................................................224.3.3 Static linking.........................................................................................................................................................22

5 SWIG Basics...................................................................................................................................................................................235.1 Running SWIG...............................................................................................................................................................24

5.1.1 Input format..........................................................................................................................................................245.1.2 SWIG Output........................................................................................................................................................255.1.3 Comments.............................................................................................................................................................255.1.4 C Preprocessor......................................................................................................................................................265.1.5 SWIG Directives..................................................................................................................................................265.1.6 Parser Limitations.................................................................................................................................................26

5.2 Wrapping Simple C Declarations...................................................................................................................................275.2.1 Basic Type Handling............................................................................................................................................285.2.2 Global Variables...................................................................................................................................................295.2.3 Constants..............................................................................................................................................................295.2.4 A brief word about const......................................................................................................................................305.2.5 A cautionary tale of char *...................................................................................................................................31

5.3 Pointers and complex objects.........................................................................................................................................315.3.1 Simple pointers.....................................................................................................................................................325.3.2 Run time pointer type checking............................................................................................................................325.3.3 Derived types, structs, and classes.......................................................................................................................325.3.4 Undefined datatypes.............................................................................................................................................335.3.5 Typedef.................................................................................................................................................................34

5.4 Other Practicalities..........................................................................................................................................................345.4.1 Passing structures by value...................................................................................................................................345.4.2 Return by value.....................................................................................................................................................355.4.3 Linking to structure variables...............................................................................................................................355.4.4 Linking to char *..................................................................................................................................................365.4.5 Arrays...................................................................................................................................................................375.4.6 Creating read-only variables.................................................................................................................................385.4.7 Renaming and ignoring declarations....................................................................................................................39

5.4.7.1 Simple renaming of specific identifiers.....................................................................................................395.4.7.2 Advanced renaming support.......................................................................................................................405.4.7.3 Limiting global renaming rules..................................................................................................................425.4.7.4 Ignoring everything then wrapping a few selected symbols......................................................................42

5.4.8 Default/optional arguments..................................................................................................................................43

SWIG-2.0 Documentation

ii

Table of Contents5 SWIG Basics

5.4.9 Pointers to functions and callbacks......................................................................................................................435.5 Structures and unions......................................................................................................................................................45

5.5.1 Typedef and structures.........................................................................................................................................465.5.2 Character strings and structures............................................................................................................................465.5.3 Array members.....................................................................................................................................................475.5.4 Structure data members........................................................................................................................................475.5.5 C constructors and destructors..............................................................................................................................485.5.6 Adding member functions to C structures............................................................................................................495.5.7 Nested structures..................................................................................................................................................525.5.8 Other things to note about structure wrapping.....................................................................................................53

5.6 Code Insertion.................................................................................................................................................................535.6.1 The output of SWIG.............................................................................................................................................535.6.2 Code insertion blocks...........................................................................................................................................545.6.3 Inlined code blocks...............................................................................................................................................555.6.4 Initialization blocks..............................................................................................................................................55

5.7 An Interface Building Strategy.......................................................................................................................................555.7.1 Preparing a C program for SWIG.........................................................................................................................555.7.2 The SWIG interface file.......................................................................................................................................565.7.3 Why use separate interface files?.........................................................................................................................565.7.4 Getting the right header files................................................................................................................................575.7.5 What to do with main().........................................................................................................................................57

6 SWIG and C++...............................................................................................................................................................................586.1 Comments on C++ Wrapping.........................................................................................................................................586.2 Approach.........................................................................................................................................................................596.3 Supported C++ features..................................................................................................................................................596.4 Command line options and compilation.........................................................................................................................606.5 Proxy classes...................................................................................................................................................................60

6.5.1 Construction of proxy classes...............................................................................................................................606.5.2 Resource management in proxies.........................................................................................................................616.5.3 Language specific details.....................................................................................................................................63

6.6 Simple C++ wrapping.....................................................................................................................................................636.6.1 Constructors and destructors................................................................................................................................636.6.2 Default constructors, copy constructors and implicit destructors........................................................................636.6.3 When constructor wrappers aren't created............................................................................................................656.6.4 Copy constructors.................................................................................................................................................656.6.5 Member functions.................................................................................................................................................666.6.6 Static members.....................................................................................................................................................676.6.7 Member data.........................................................................................................................................................67

6.7 Default arguments...........................................................................................................................................................696.8 Protection........................................................................................................................................................................706.9 Enums and constants.......................................................................................................................................................706.10 Friends..........................................................................................................................................................................706.11 References and pointers................................................................................................................................................716.12 Pass and return by value...............................................................................................................................................726.13 Inheritance....................................................................................................................................................................736.14 A brief discussion of multiple inheritance, pointers, and type checking......................................................................746.15 Wrapping Overloaded Functions and Methods............................................................................................................76

6.15.1 Dispatch function generation..............................................................................................................................766.15.2 Ambiguity in Overloading..................................................................................................................................776.15.3 Ambiguity resolution and renaming...................................................................................................................786.15.4 Comments on overloading..................................................................................................................................82

6.16 Wrapping overloaded operators....................................................................................................................................82

SWIG-2.0 Documentation

iii

Table of Contents6 SWIG and C++

6.17 Class extension.............................................................................................................................................................846.18 Templates......................................................................................................................................................................856.19 Namespaces..................................................................................................................................................................93

6.19.1 The nspace feature for namespaces....................................................................................................................986.20 Renaming templated types in namespaces...................................................................................................................986.21 Exception specifications...............................................................................................................................................996.22 Exception handling with %catches.............................................................................................................................1006.23 Pointers to Members...................................................................................................................................................1006.24 Smart pointers and operator->().................................................................................................................................1016.25 C++ reference counted objects - ref/unref feature......................................................................................................1036.26 Using declarations and inheritance.............................................................................................................................1056.27 Nested classes.............................................................................................................................................................1066.28 A brief rant about const-correctness...........................................................................................................................1086.29 Where to go for more information..............................................................................................................................109

7 Preprocessing................................................................................................................................................................................1107.1 File inclusion................................................................................................................................................................1107.2 File imports...................................................................................................................................................................1107.3 Conditional Compilation..............................................................................................................................................1107.4 Macro Expansion..........................................................................................................................................................1117.5 SWIG Macros...............................................................................................................................................................1127.6 C99 and GNU Extensions.............................................................................................................................................1127.7 Preprocessing and delimiters........................................................................................................................................113

7.7.1 Preprocessing and %{ ... %} & " ... " delimiters................................................................................................1137.7.2 Preprocessing and { ... } delimiters....................................................................................................................113

7.8 Preprocessor and Typemaps.........................................................................................................................................1137.9 Viewing preprocessor output........................................................................................................................................1147.10 The #error and #warning directives............................................................................................................................114

8 SWIG library................................................................................................................................................................................1158.1 The %include directive and library search path...........................................................................................................1158.2 C Arrays and Pointers...................................................................................................................................................115

8.2.1 cpointer.i.............................................................................................................................................................1168.2.2 carrays.i..............................................................................................................................................................1178.2.3 cmalloc.i.............................................................................................................................................................1198.2.4 cdata.i..................................................................................................................................................................120

8.3 C String Handling.........................................................................................................................................................1218.3.1 Default string handling.......................................................................................................................................1218.3.2 Passing binary data.............................................................................................................................................1228.3.3 Using %newobject to release memory...............................................................................................................1228.3.4 cstring.i...............................................................................................................................................................122

8.4 STL/C++ Library..........................................................................................................................................................1268.4.1 std::string............................................................................................................................................................1278.4.2 std::vector...........................................................................................................................................................1278.4.3 STL exceptions...................................................................................................................................................1298.4.4 shared_ptr smart pointer.....................................................................................................................................130

8.5 Utility Libraries............................................................................................................................................................1328.5.1 exception.i..........................................................................................................................................................132

9 Argument Handling.....................................................................................................................................................................1339.1 The typemaps.i library..................................................................................................................................................133

9.1.1 Introduction........................................................................................................................................................1339.1.2 Input parameters.................................................................................................................................................134

SWIG-2.0 Documentation

iv

Table of Contents9 Argument Handling

9.1.3 Output parameters..............................................................................................................................................1359.1.4 Input/Output parameters.....................................................................................................................................1369.1.5 Using different names.........................................................................................................................................136

9.2 Applying constraints to input values............................................................................................................................1379.2.1 Simple constraint example.................................................................................................................................1379.2.2 Constraint methods.............................................................................................................................................1379.2.3 Applying constraints to new datatypes...............................................................................................................137

10 Typemaps....................................................................................................................................................................................13910.1 Introduction.................................................................................................................................................................140

10.1.1 Type conversion...............................................................................................................................................14010.1.2 Typemaps.........................................................................................................................................................14110.1.3 Pattern matching...............................................................................................................................................14210.1.4 Reusing typemaps.............................................................................................................................................14310.1.5 What can be done with typemaps?...................................................................................................................14310.1.6 What can't be done with typemaps?.................................................................................................................14410.1.7 Similarities to Aspect Oriented Programming.................................................................................................14510.1.8 The rest of this chapter.....................................................................................................................................145

10.2 Typemap specifications..............................................................................................................................................14510.2.1 Defining a typemap..........................................................................................................................................14510.2.2 Typemap scope.................................................................................................................................................14710.2.3 Copying a typemap...........................................................................................................................................14710.2.4 Deleting a typemap...........................................................................................................................................14810.2.5 Placement of typemaps.....................................................................................................................................148

10.3 Pattern matching rules................................................................................................................................................14910.3.1 Basic matching rules.........................................................................................................................................14910.3.2 Typedef reductions matching...........................................................................................................................15010.3.3 Default typemap matching rules.......................................................................................................................15210.3.4 Multi-arguments typemaps...............................................................................................................................15310.3.5 Matching rules compared to C++ templates.....................................................................................................15310.3.6 Debugging typemap pattern matching..............................................................................................................155

10.4 Code generation rules.................................................................................................................................................15710.4.1 Scope................................................................................................................................................................15710.4.2 Declaring new local variables..........................................................................................................................15810.4.3 Special variables...............................................................................................................................................15910.4.4 Special variable macros....................................................................................................................................161

10.4.4.1 $descriptor(type)....................................................................................................................................16110.4.4.2 $typemap(method, typepattern).............................................................................................................162

10.5 Common typemap methods........................................................................................................................................16210.5.1 "in" typemap.....................................................................................................................................................16210.5.2 "typecheck" typemap........................................................................................................................................16310.5.3 "out" typemap...................................................................................................................................................16310.5.4 "arginit" typemap..............................................................................................................................................16310.5.5 "default" typemap.............................................................................................................................................16410.5.6 "check" typemap...............................................................................................................................................16410.5.7 "argout" typemap..............................................................................................................................................16410.5.8 "freearg" typemap.............................................................................................................................................16410.5.9 "newfree" typemap...........................................................................................................................................16510.5.10 "memberin" typemap......................................................................................................................................16510.5.11 "varin" typemap..............................................................................................................................................16510.5.12 "varout" typemap............................................................................................................................................16510.5.13 "throws" typemap...........................................................................................................................................166

10.6 Some typemap examples............................................................................................................................................166

SWIG-2.0 Documentation

v

Table of Contents10 Typemaps

10.6.1 Typemaps for arrays.........................................................................................................................................16610.6.2 Implementing constraints with typemaps.........................................................................................................169

10.7 Typemaps for multiple target languages.....................................................................................................................16910.8 Optimal code generation when returning by value.....................................................................................................17010.9 Multi-argument typemaps...........................................................................................................................................17210.10 Typemap warnings....................................................................................................................................................17410.11 Typemap fragments..................................................................................................................................................174

10.11.1 Fragment type specialization..........................................................................................................................17710.11.2 Fragments and automatic typemap specialization..........................................................................................177

10.12 The run-time type checker........................................................................................................................................17810.12.1 Implementation...............................................................................................................................................17810.12.2 Usage..............................................................................................................................................................180

10.13 Typemaps and overloading.......................................................................................................................................18110.14 More about %apply and %clear................................................................................................................................18410.15 Passing data between typemaps................................................................................................................................18510.16 C++ "this" pointer.....................................................................................................................................................18510.17 Where to go for more information?..........................................................................................................................186

11 Customization Features.............................................................................................................................................................18711.1 Exception handling with %exception.........................................................................................................................187

11.1.1 Handling exceptions in C code.........................................................................................................................18811.1.2 Exception handling with longjmp()..................................................................................................................18811.1.3 Handling C++ exceptions.................................................................................................................................18911.1.4 Exception handlers for variables......................................................................................................................19011.1.5 Defining different exception handlers..............................................................................................................19011.1.6 Special variables for %exception.....................................................................................................................19111.1.7 Using The SWIG exception library..................................................................................................................192

11.2 Object ownership and %newobject............................................................................................................................19311.3 Features and the %feature directive............................................................................................................................194

11.3.1 Feature attributes..............................................................................................................................................19511.3.2 Feature flags.....................................................................................................................................................19611.3.3 Clearing features...............................................................................................................................................19711.3.4 Features and default arguments........................................................................................................................19811.3.5 Feature example................................................................................................................................................198

12 Contracts.....................................................................................................................................................................................20012.1 The %contract directive..............................................................................................................................................20012.2 %contract and classes.................................................................................................................................................20012.3 Constant aggregation and %aggregate_check............................................................................................................20112.4 Notes...........................................................................................................................................................................202

13 Variable Length Arguments.....................................................................................................................................................20313.1 Introduction.................................................................................................................................................................20313.2 The Problem................................................................................................................................................................20413.3 Default varargs support...............................................................................................................................................20513.4 Argument replacement using %varargs......................................................................................................................20513.5 Varargs and typemaps.................................................................................................................................................20613.6 Varargs wrapping with libffi......................................................................................................................................20813.7 Wrapping of va_list....................................................................................................................................................21113.8 C++ Issues..................................................................................................................................................................21213.9 Discussion...................................................................................................................................................................212

SWIG-2.0 Documentation

vi

Table of Contents14 Warning Messages.....................................................................................................................................................................214

14.1 Introduction.................................................................................................................................................................21414.2 Warning message suppression....................................................................................................................................21414.3 Enabling extra warnings.............................................................................................................................................21514.4 Issuing a warning message.........................................................................................................................................21614.5 Symbolic symbols.......................................................................................................................................................21614.6 Commentary...............................................................................................................................................................21614.7 Warnings as errors......................................................................................................................................................21614.8 Message output format...............................................................................................................................................21714.9 Warning number reference.........................................................................................................................................217

14.9.1 Deprecated features (100-199).........................................................................................................................21714.9.2 Preprocessor (200-299)....................................................................................................................................21714.9.3 C/C++ Parser (300-399)...................................................................................................................................21714.9.4 Types and typemaps (400-499)........................................................................................................................21914.9.5 Code generation (500-599)...............................................................................................................................21914.9.6 Language module specific (700-899)...............................................................................................................22014.9.7 User defined (900-999).....................................................................................................................................220

14.10 History......................................................................................................................................................................221

15 Working with Modules..............................................................................................................................................................22215.1 Modules Introduction..................................................................................................................................................22215.2 Basics..........................................................................................................................................................................22215.3 The SWIG runtime code.............................................................................................................................................22315.4 External access to the runtime....................................................................................................................................22415.5 A word of caution about static libraries......................................................................................................................22515.6 References...................................................................................................................................................................22515.7 Reducing the wrapper file size...................................................................................................................................225

16 Using SWIG with ccache - ccache-swig(1) manpage..............................................................................................................22616.1 NAME.........................................................................................................................................................................22616.2 SYNOPSIS.................................................................................................................................................................22616.3 DESCRIPTION..........................................................................................................................................................22616.4 OPTIONS SUMMARY..............................................................................................................................................22616.5 OPTIONS...................................................................................................................................................................22716.6 INSTALLATION.......................................................................................................................................................22716.7 EXTRA OPTIONS.....................................................................................................................................................22716.8 ENVIRONMENT VARIABLES................................................................................................................................22816.9 CACHE SIZE MANAGEMENT...............................................................................................................................22916.10 CACHE COMPRESSION........................................................................................................................................22916.11 HOW IT WORKS.....................................................................................................................................................23016.12 USING CCACHE WITH DISTCC..........................................................................................................................23016.13 SHARING A CACHE..............................................................................................................................................23016.14 HISTORY.................................................................................................................................................................23016.15 DIFFERENCES FROM COMPILERCACHE.........................................................................................................23116.16 CREDITS..................................................................................................................................................................23116.17 AUTHOR..................................................................................................................................................................231

17 SWIG and Allegro Common Lisp............................................................................................................................................23217.1 Basics..........................................................................................................................................................................233

17.1.1 Running SWIG.................................................................................................................................................23317.1.2 Command Line Options...................................................................................................................................23517.1.3 Inserting user code into generated files............................................................................................................236

17.2 Wrapping Overview....................................................................................................................................................23617.2.1 Function Wrapping...........................................................................................................................................236

SWIG-2.0 Documentation

vii

Table of Contents17 SWIG and Allegro Common Lisp

17.2.2 Foreign Wrappers.............................................................................................................................................23717.2.3 FFI Wrappers....................................................................................................................................................23717.2.4 Non-overloaded Defuns....................................................................................................................................23817.2.5 Overloaded Defuns...........................................................................................................................................23817.2.6 What about constant and variable access?........................................................................................................23817.2.7 Object Wrapping..............................................................................................................................................239

17.3 Wrapping Details........................................................................................................................................................23917.3.1 Namespaces......................................................................................................................................................23917.3.2 Constants..........................................................................................................................................................24017.3.3 Variables...........................................................................................................................................................24017.3.4 Enumerations....................................................................................................................................................24117.3.5 Arrays...............................................................................................................................................................24217.3.6 Classes and Structs and Unions (oh my!).........................................................................................................244

17.3.6.1 CLOS wrapping of.................................................................................................................................24517.3.6.2 CLOS Inheritance...................................................................................................................................24517.3.6.3 Member fields and functions..................................................................................................................24517.3.6.4 Why not directly access C++ classes using foreign types?....................................................................245

17.3.7 Templates.........................................................................................................................................................24517.3.7.1 Generating wrapper code for templates.................................................................................................24517.3.7.2 Implicit Template instantiation..............................................................................................................245

17.3.8 Typedef, Templates, and Synonym Types.......................................................................................................24517.3.8.1 Choosing a primary type........................................................................................................................246

17.3.9 Function overloading/Parameter defaulting.....................................................................................................24617.3.10 Operator wrapping and Operator overloading................................................................................................24917.3.11 Varargs...........................................................................................................................................................25017.3.12 C++ Exceptions..............................................................................................................................................25117.3.13 Pass by value, pass by reference.....................................................................................................................251

17.4 Typemaps....................................................................................................................................................................25117.4.1 Code Generation in the C++ Wrapper..............................................................................................................251

17.4.1.1 IN Typemap............................................................................................................................................25117.4.1.2 OUT Typemap........................................................................................................................................25217.4.1.3 CTYPE Typemap...................................................................................................................................252

17.4.2 Code generation in Lisp wrappers....................................................................................................................25217.4.2.1 LIN Typemap.........................................................................................................................................25217.4.2.2 LOUT Typemap.....................................................................................................................................25317.4.2.3 FFITYPE Typemap................................................................................................................................25317.4.2.4 LISPTYPE Typemap..............................................................................................................................25417.4.2.5 LISPCLASS Typemap...........................................................................................................................254

17.4.3 Modifying SWIG behavior using typemaps.....................................................................................................25417.5 Identifier Converter functions.....................................................................................................................................255

17.5.1 Creating symbols in the lisp environment........................................................................................................25517.5.2 Existing identifier-converter functions.............................................................................................................255

17.5.2.1 identifier-convert-null............................................................................................................................25517.5.2.2 identifier-convert-lispify........................................................................................................................25517.5.2.3 Default identifier to symbol conversions...............................................................................................255

17.5.3 Defining your own identifier-converter............................................................................................................25517.5.4 Instructing SWIG to use a particular identifier-converter................................................................................256

18 SWIG and Android....................................................................................................................................................................25718.1 Overview.....................................................................................................................................................................25718.2 Android examples.......................................................................................................................................................257

18.2.1 Examples introduction......................................................................................................................................25718.2.2 Simple C example.............................................................................................................................................257

SWIG-2.0 Documentation

viii

Table of Contents18 SWIG and Android

18.2.3 C++ class example............................................................................................................................................26118.2.4 Other examples.................................................................................................................................................266

18.3 C++ STL.....................................................................................................................................................................266

19 SWIG and C#.............................................................................................................................................................................26719.1 Introduction.................................................................................................................................................................26719.2 Differences to the Java module...................................................................................................................................26719.3 Void pointers..............................................................................................................................................................27119.4 C# Arrays....................................................................................................................................................................271

19.4.1 The SWIG C arrays library...............................................................................................................................27219.4.2 Managed arrays using P/Invoke default array marshalling..............................................................................27219.4.3 Managed arrays using pinning..........................................................................................................................273

19.5 C# Exceptions.............................................................................................................................................................27419.5.1 C# exception example using "check" typemap................................................................................................27519.5.2 C# exception example using %exception.........................................................................................................27719.5.3 C# exception example using exception specifications.....................................................................................27819.5.4 Custom C# ApplicationException example.....................................................................................................278

19.6 C# Directors................................................................................................................................................................28019.6.1 Directors example.............................................................................................................................................28019.6.2 Directors implementation.................................................................................................................................28119.6.3 Director caveats................................................................................................................................................284

19.7 Multiples modules......................................................................................................................................................28419.8 C# Typemap examples...............................................................................................................................................285

19.8.1 Memory management when returning references to member variables..........................................................28519.8.2 Memory management for objects passed to the C++ layer..............................................................................28619.8.3 Date marshalling using the csin typemap and associated attributes.................................................................28819.8.4 A date example demonstrating marshalling of C# properties..........................................................................29119.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors...........................................29219.8.6 Turning wrapped classes into partial classes....................................................................................................29319.8.7 Extending proxy classes with additional C# code............................................................................................29419.8.8 Underlying type for enums...............................................................................................................................294

20 SWIG and Chicken....................................................................................................................................................................29520.1 Preliminaries...............................................................................................................................................................295

20.1.1 Running SWIG in C mode...............................................................................................................................29520.1.2 Running SWIG in C++ mode...........................................................................................................................296

20.2 Code Generation.........................................................................................................................................................29620.2.1 Naming Conventions........................................................................................................................................29620.2.2 Modules............................................................................................................................................................29620.2.3 Constants and Variables...................................................................................................................................29620.2.4 Functions..........................................................................................................................................................29720.2.5 Exceptions........................................................................................................................................................297

20.3 TinyCLOS...................................................................................................................................................................29720.4 Linkage.......................................................................................................................................................................298

20.4.1 Static binary or shared library linked at compile time.....................................................................................29820.4.2 Building chicken extension libraries................................................................................................................29820.4.3 Linking multiple SWIG modules with TinyCLOS..........................................................................................299

20.5 Typemaps....................................................................................................................................................................29920.6 Pointers.......................................................................................................................................................................299

20.6.1 Garbage collection............................................................................................................................................30020.7 Unsupported features and known problems...............................................................................................................300

20.7.1 TinyCLOS problems with Chicken version

Table of Contents21 SWIG and D...............................................................................................................................................................................302

21.1 Introduction.................................................................................................................................................................30221.2 Command line invocation...........................................................................................................................................30221.3 Typemaps....................................................................................................................................................................303

21.3.1 C# D name comparison.............................................................................................................................30321.3.2 ctype, imtype, dtype.........................................................................................................................................30321.3.3 in, out, directorin, directorout...........................................................................................................................30321.3.4 din, dout, ddirectorin, ddirectorout...................................................................................................................30421.3.5 typecheck typemaps..........................................................................................................................................30421.3.6 Code injection typemaps..................................................................................................................................30421.3.7 Special variable macros....................................................................................................................................305

21.4 %features....................................................................................................................................................................30721.5 Pragmas.......................................................................................................................................................................30721.6 D Exceptions...............................................................................................................................................................30821.7 D Directors..................................................................................................................................................................30821.8 Other features..............................................................................................................................................................308

21.8.1 Extended namespace support (nspace).............................................................................................................30821.8.2 Native pointer support......................................................................................................................................30821.8.3 Operator overloading........................................................................................................................................30921.8.4 Running the test-suite.......................................................................................................................................309

21.9 D Typemap examples.................................................................................................................................................30921.10 Work in progress and planned features....................................................................................................................309

22 SWIG and Go.............................................................................................................................................................................31022.1 Overview.....................................................................................................................................................................31022.2 Running SWIG with Go.............................................................................................................................................310

22.2.1 Additional Commandline Options....................................................................................................................31022.2.2 Go Output Files................................................................................................................................................311

22.3 A tour of basic C/C++ wrapping................................................................................................................................31122.3.1 Go Package Name............................................................................................................................................31122.3.2 Go Names.........................................................................................................................................................31122.3.3 Go Constants....................................................................................................................................................31222.3.4 Go Enumerations..............................................................................................................................................31222.3.5 Go Classes........................................................................................................................................................312

22.3.5.1 Go Class Inheritance..............................................................................................................................31322.3.6 Go Templates....................................................................................................................................................31322.3.7 Go Director Classes..........................................................................................................................................31322.3.8 Default Go primitive type mappings................................................................................................................31322.3.9 Output arguments.............................................................................................................................................31422.3.10 Adding additional go code..............................................................................................................................314

23 SWIG and Guile.........................................................................................................................................................................31623.1 Supported Guile Versions...........................................................................................................................................31623.2 Meaning of "Module".................................................................................................................................................31623.3 Old GH Guile API......................................................................................................................................................31623.4 Linkage.......................................................................................................................................................................316

23.4.1 Simple Linkage.................................................................................................................................................31723.4.2 Passive Linkage................................................................................................................................................31723.4.3 Native Guile Module Linkage..........................................................................................................................31823.4.4 Old Auto-Loading Guile Module Linkage.......................................................................................................31823.4.5 Hobbit4D Linkage............................................................................................................................................318

23.5 Underscore Folding....................................................................................................................................................31823.6 Typemaps....................................................................................................................................................................31923.7 Representation of pointers as smobs...........................................................................................................................319

SWIG-2.0 Documentation

x

Table of Contents23 SWIG and Guile

23.7.1 Smobs...............................................................................................................................................................32023.7.2 Garbage Collection...........................................................................................................................................320

23.8 Exception Handling....................................................................................................................................................32023.9 Procedure documentation...........................................................................................................................................32023.10 Procedures with setters.............................................................................................................................................32123.11 GOOPS Proxy Classes..............................................................................................................................................321

23.11.1 Naming Issues................................................................................................................................................32323.11.2 Linking...........................................................................................................................................................323

24 SWIG and Java..........................................................................................................................................................................32624.1 Overview.....................................................................................................................................................................32824.2 Preliminaries...............................................................................................................................................................328

24.2.1 Running SWIG.................................................................................................................................................32824.2.2 Additional Commandline Options....................................................................................................................32924.2.3 Getting the right header files............................................................................................................................32924.2.4 Compiling a dynamic module..........................................................................................................................32924.2.5 Using your module...........................................................................................................................................33024.2.6 Dynamic linking problems...............................................................................................................................33024.2.7 Compilation