"Fossies" - the Fresh Open Source Software Archive

Member "swig-4.1.1/Doc/Manual/SWIGDocumentation.html" (30 Nov 2022, 2432474 Bytes) of package /linux/misc/swig-4.1.1.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!DOCTYPE html>
    2 <HTML>
    3 <HEAD>
    4 <TITLE>SWIG-4.1 Documentation</TITLE>
    5 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
    6 <STYLE TYPE="text/css"><!--
    8 div.sectiontoc {
    9   border-style: dotted;
   10   border-width: 2px;
   11   padding: 2pt;
   12 }
   14 h2 { 
   15   padding: 3px;
   16   color: #000000;
   17   border-bottom: 2px 
   18   solid #dddddd; 
   19 }
   21 h3, h4 {
   22   margin-left: 1em;
   23 }
   25 p,li,table,dl {
   26   margin-left: 2em;
   27   margin-right: 2em;
   28 }
   30 div.indent {
   31   margin-left: 4em;
   32   margin-right: 4em;
   33 }
   35 div.code {
   36   border-style: solid; 
   37   border-width: 1px; 
   38   padding: 2pt; 
   39   margin-left: 4em;
   40   margin-right: 4em;
   41   background-color: #F0FFFF;
   42   font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
   43 }
   45 div.targetlang {
   46   border-style: solid; 
   47   border-width: 1px; 
   48   padding: 2pt; 
   49   margin-left: 4em;
   50   margin-right: 4em;
   51   background-color: #d7f6bb;
   52   font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
   53 }
   55 div.shell {
   56   border-style: solid; 
   57   border-width: 1px; 
   58   padding: 2pt; 
   59   margin-left: 4em;
   60   margin-right: 4em;
   61   background-color: #DCDCDC;
   62   font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
   63 }
   65 div.diagram {
   66   border-style: solid; 
   67   border-width: 1px; 
   68   padding: 2pt; 
   69   margin-left: 4em;
   70   margin-right: 4em;
   71   background-color: #FFEBCD;
   72   font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
   73 }
   75 div.diagram li {
   76     margin-left: 0;
   77 }
   79 ul li p {
   80   margin-left: 0;
   81   margin-right: 0;
   82 }
   84 ol li p {
   85   margin-left: 0;
   86   margin-right: 0;
   87 }
   89 dl dd p {
   90   margin-left: 0;
   91   margin-right: 0;
   92 }
   94 div.indent p {
   95   margin-left: 0;
   96   margin-right: 0;
   97 }
   99 pre, code, tt {
  100   font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
  101 }
  103 body { font-family: serif; }
  105 --></STYLE>
  106 </HEAD>
  107 <BODY BGCOLOR="#ffffff" LINK="#0000ff" VLINK="#0000ff" ALINK="#0000ff">
  108 <CENTER><A HREF="#CONTENTS"><IMG SRC="swig16.png" BORDER="0" WIDTH="167" HEIGHT="85" ALT="SWIG-4.1 Documentation"><BR>
  109 <H1>SWIG-4.1 Documentation</H1></A><BR>
  110 </CENTER>
  111 <HR NOSHADE>
  112 <h1 ALIGN="CENTER"><a NAME="CONTENTS">Table of Contents</a></h1>
  113 <br>
  114 <br><b><a HREF="#Sections">SWIG-4.1 Documentation</a></b>
  115 <ul>
  116 <li><a HREF="#Sections_Sections">Sections</a>
  117 <ul>
  118 <li><a HREF="#Sections_core_docs">SWIG Core Documentation</a></li>
  119 <li><a HREF="#Sections_language_modules">Supported Language Modules
  120  Documentation</a></li>
  121 <li><a HREF="#Sections_experimental_language_modules">Experimental
  122  Language Modules Documentation</a></li>
  123 <li><a HREF="#Sections_developers_docs">Developer Documentation</a></li>
  124 </ul>
  125 </li>
  126 </ul>
  127 <b><a HREF="#Preface">1 Preface</a></b>
  128 <ul>
  129 <li><a HREF="#Preface_nn2">1.1 Introduction</a></li>
  130 <li><a HREF="#Preface_nn4">1.2 SWIG Versions</a></li>
  131 <li><a HREF="#Preface_license">1.3 SWIG License</a></li>
  132 <li><a HREF="#Preface_nn5">1.4 SWIG resources</a></li>
  133 <li><a HREF="#Preface_nn6">1.5 Prerequisites</a></li>
  134 <li><a HREF="#Preface_nn7">1.6 Organization of this manual</a></li>
  135 <li><a HREF="#Preface_nn8">1.7 How to avoid reading the manual</a></li>
  136 <li><a HREF="#Preface_nn9">1.8 Backwards compatibility</a></li>
  137 <li><a HREF="#Preface_release_notes">1.9 Release notes</a></li>
  138 <li><a HREF="#Preface_nn10">1.10 Credits</a></li>
  139 <li><a HREF="#Preface_nn11">1.11 Bug reports</a></li>
  140 <li><a HREF="#Preface_installation">1.12 Installation</a>
  141 <ul>
  142 <li><a HREF="#Preface_windows_installation">1.12.1 Windows installation</a>
  143 </li>
  144 <li><a HREF="#Preface_unix_installation">1.12.2 Unix installation</a></li>
  145 <li><a HREF="#Preface_osx_installation">1.12.3 Macintosh OS X
  146  installation</a></li>
  147 <li><a HREF="#Preface_testing">1.12.4 Testing</a></li>
  148 <li><a HREF="#Preface_examples">1.12.5 Examples</a></li>
  149 </ul>
  150 </li>
  151 </ul>
  152 <b><a HREF="#Introduction">2 Introduction</a></b>
  153 <ul>
  154 <li><a HREF="#Introduction_nn2">2.1 What is SWIG?</a></li>
  155 <li><a HREF="#Introduction_nn3">2.2 Why use SWIG?</a></li>
  156 <li><a HREF="#Introduction_target_languages">2.3 Target languages</a>
  157 <ul>
  158 <li><a HREF="#Introduction_supported_status">2.3.1 Supported status</a></li>
  159 <li><a HREF="#Introduction_experimental_status">2.3.2 Experimental
  160  status</a></li>
  161 </ul>
  162 </li>
  163 <li><a HREF="#Introduction_nn4">2.4 A SWIG example</a>
  164 <ul>
  165 <li><a HREF="#Introduction_nn5">2.4.1 SWIG interface file</a></li>
  166 <li><a HREF="#Introduction_nn6">2.4.2 The swig command</a></li>
  167 <li><a HREF="#Introduction_nn7">2.4.3 Building a Perl5 module</a></li>
  168 <li><a HREF="#Introduction_nn8">2.4.4 Building a Python module</a></li>
  169 <li><a HREF="#Introduction_nn9">2.4.5 Shortcuts</a></li>
  170 </ul>
  171 </li>
  172 <li><a HREF="#Introduction_nn10">2.5 Supported C/C++ language features</a>
  173 </li>
  174 <li><a HREF="#Introduction_nn11">2.6 Non-intrusive interface building</a>
  175 </li>
  176 <li><a HREF="#Introduction_build_system">2.7 Incorporating SWIG into a
  177  build system</a></li>
  178 <li><a HREF="#Introduction_nn12">2.8 Hands off code generation</a></li>
  179 <li><a HREF="#Introduction_nn13">2.9 SWIG and freedom</a></li>
  180 </ul>
  181 <b><a HREF="#Windows">3 Getting started on Windows</a></b>
  182 <ul>
  183 <li><a HREF="#Windows_installation">3.1 Installation on Windows</a>
  184 <ul>
  185 <li><a HREF="#Windows_executable">3.1.1 Windows Executable</a></li>
  186 </ul>
  187 </li>
  188 <li><a HREF="#Windows_examples">3.2 SWIG Windows Examples</a>
  189 <ul>
  190 <li><a HREF="#Windows_visual_studio">3.2.1 Instructions for using the
  191  Examples with Visual Studio</a>
  192 <ul>
  193 <li><a HREF="#Windows_csharp"> C#</a></li>
  194 <li><a HREF="#Windows_java"> Java</a></li>
  195 <li><a HREF="#Windows_perl"> Perl</a></li>
  196 <li><a HREF="#Windows_python"> Python</a></li>
  197 <li><a HREF="#Windows_tcl"> TCL</a></li>
  198 <li><a HREF="#Windows_r"> R</a></li>
  199 <li><a HREF="#Windows_ruby"> Ruby</a></li>
  200 </ul>
  201 </li>
  202 <li><a HREF="#Windows_other_compilers">3.2.2 Instructions for using the
  203  Examples with other compilers</a></li>
  204 </ul>
  205 </li>
  206 <li><a HREF="#Windows_swig_exe">3.3 Building swig.exe on Windows</a>
  207 <ul>
  208 <li><a HREF="#Windows_cmake">3.3.1 Building swig.exe using CMake</a></li>
  209 <li><a HREF="#Windows_msys2">3.3.2 Building swig.exe using MSYS2</a></li>
  210 <li><a HREF="#Windows_mingw_msys">3.3.3 Building swig.exe using MinGW
  211  and MSYS</a></li>
  212 <li><a HREF="#Windows_cygwin">3.3.4 Building swig.exe using Cygwin</a>
  213 <ul>
  214 <li><a HREF="#Windows_examples_cygwin"> Running the examples on
  215  Windows using Cygwin</a></li>
  216 </ul>
  217 </li>
  218 </ul>
  219 </li>
  220 <li><a HREF="#Windows_interface_file">3.4 Microsoft extensions and other
  221  Windows quirks</a></li>
  222 </ul>
  223 <b><a HREF="#Scripting">4 Scripting Languages</a></b>
  224 <ul>
  225 <li><a HREF="#Scripting_nn2">4.1 The two language view of the world</a></li>
  226 <li><a HREF="#Scripting_nn3">4.2 How does a scripting language talk to
  227  C?</a>
  228 <ul>
  229 <li><a HREF="#Scripting_nn4">4.2.1 Wrapper functions</a></li>
  230 <li><a HREF="#Scripting_nn5">4.2.2 Variable linking</a></li>
  231 <li><a HREF="#Scripting_nn6">4.2.3 Constants</a></li>
  232 <li><a HREF="#Scripting_nn7">4.2.4 Structures and classes</a></li>
  233 <li><a HREF="#Scripting_nn8">4.2.5 Proxy classes</a></li>
  234 </ul>
  235 </li>
  236 <li><a HREF="#Scripting_nn9">4.3 Building scripting language extensions</a>
  237 <ul>
  238 <li><a HREF="#Scripting_nn10">4.3.1 Shared libraries and dynamic loading</a>
  239 </li>
  240 <li><a HREF="#Scripting_nn11">4.3.2 Linking with shared libraries</a></li>
  241 <li><a HREF="#Scripting_nn12">4.3.3 Static linking</a></li>
  242 </ul>
  243 </li>
  244 </ul>
  245 <b><a HREF="#SWIG">5 SWIG Basics</a></b>
  246 <ul>
  247 <li><a HREF="#SWIG_nn2">5.1 Running SWIG</a>
  248 <ul>
  249 <li><a HREF="#SWIG_nn3">5.1.1 Input format</a></li>
  250 <li><a HREF="#SWIG_output">5.1.2 SWIG Output</a></li>
  251 <li><a HREF="#SWIG_nn5">5.1.3 Comments</a></li>
  252 <li><a HREF="#SWIG_nn6">5.1.4 C Preprocessor</a></li>
  253 <li><a HREF="#SWIG_nn7">5.1.5 SWIG Directives</a></li>
  254 <li><a HREF="#SWIG_nn8">5.1.6 Parser Limitations</a></li>
  255 </ul>
  256 </li>
  257 <li><a HREF="#SWIG_nn9">5.2 Wrapping Simple C Declarations</a>
  258 <ul>
  259 <li><a HREF="#SWIG_nn10">5.2.1 Basic Type Handling</a></li>
  260 <li><a HREF="#SWIG_nn11">5.2.2 Global Variables</a></li>
  261 <li><a HREF="#SWIG_nn12">5.2.3 Constants</a></li>
  262 <li><a HREF="#SWIG_nn13">5.2.4 A brief word about const</a></li>
  263 <li><a HREF="#SWIG_nn14">5.2.5 A cautionary tale of char *</a></li>
  264 </ul>
  265 </li>
  266 <li><a HREF="#SWIG_nn15">5.3 Pointers and complex objects</a>
  267 <ul>
  268 <li><a HREF="#SWIG_nn16">5.3.1 Simple pointers</a></li>
  269 <li><a HREF="#SWIG_nn17">5.3.2 Run time pointer type checking</a></li>
  270 <li><a HREF="#SWIG_nn18">5.3.3 Derived types, structs, and classes</a></li>
  271 <li><a HREF="#SWIG_nn19">5.3.4 Undefined datatypes</a></li>
  272 <li><a HREF="#SWIG_nn20">5.3.5 Typedef</a></li>
  273 </ul>
  274 </li>
  275 <li><a HREF="#SWIG_nn21">5.4 Other Practicalities</a>
  276 <ul>
  277 <li><a HREF="#SWIG_nn22">5.4.1 Passing structures by value</a></li>
  278 <li><a HREF="#SWIG_nn23">5.4.2 Return by value</a></li>
  279 <li><a HREF="#SWIG_nn24">5.4.3 Linking to structure variables</a></li>
  280 <li><a HREF="#SWIG_nn25">5.4.4 Linking to char *</a></li>
  281 <li><a HREF="#SWIG_nn26">5.4.5 Arrays</a></li>
  282 <li><a HREF="#SWIG_readonly_variables">5.4.6 Creating read-only
  283  variables</a></li>
  284 <li><a HREF="#SWIG_rename_ignore">5.4.7 Renaming and ignoring
  285  declarations</a>
  286 <ul>
  287 <li><a HREF="#SWIG_nn29"> Simple renaming of specific identifiers</a>
  288 </li>
  289 <li><a HREF="#SWIG_ignore"> Ignoring identifiers</a></li>
  290 <li><a HREF="#SWIG_advanced_renaming"> Advanced renaming support</a>
  291 </li>
  292 <li><a HREF="#SWIG_limiting_renaming"> Limiting global renaming
  293  rules</a></li>
  294 <li><a HREF="#SWIG_chosen_unignore"> Ignoring everything then
  295  wrapping a few selected symbols</a></li>
  296 </ul>
  297 </li>
  298 <li><a HREF="#SWIG_default_args">5.4.8 Default/optional arguments</a></li>
  299 <li><a HREF="#SWIG_nn30">5.4.9 Pointers to functions and callbacks</a></li>
  300 </ul>
  301 </li>
  302 <li><a HREF="#SWIG_nn31">5.5 Structures and unions</a>
  303 <ul>
  304 <li><a HREF="#SWIG_nn32">5.5.1 Typedef and structures</a></li>
  305 <li><a HREF="#SWIG_nn33">5.5.2 Character strings and structures</a></li>
  306 <li><a HREF="#SWIG_nn34">5.5.3 Array members</a></li>
  307 <li><a HREF="#SWIG_structure_data_members">5.5.4 Structure data members</a>
  308 </li>
  309 <li><a HREF="#SWIG_nn36">5.5.5 C constructors and destructors</a></li>
  310 <li><a HREF="#SWIG_adding_member_functions">5.5.6 Adding member
  311  functions to C structures</a></li>
  312 <li><a HREF="#SWIG_nested_structs">5.5.7 Nested structures</a></li>
  313 <li><a HREF="#SWIG_nn39">5.5.8 Other things to note about structure
  314  wrapping</a></li>
  315 </ul>
  316 </li>
  317 <li><a HREF="#SWIG_nn40">5.6 Code Insertion</a>
  318 <ul>
  319 <li><a HREF="#SWIG_nn41">5.6.1 The output of SWIG</a></li>
  320 <li><a HREF="#SWIG_nn42">5.6.2 Code insertion blocks</a></li>
  321 <li><a HREF="#SWIG_nn43">5.6.3 Inlined code blocks</a></li>
  322 <li><a HREF="#SWIG_nn44">5.6.4 Initialization blocks</a></li>
  323 </ul>
  324 </li>
  325 <li><a HREF="#SWIG_nn45">5.7 An Interface Building Strategy</a>
  326 <ul>
  327 <li><a HREF="#SWIG_nn46">5.7.1 Preparing a C program for SWIG</a></li>
  328 <li><a HREF="#SWIG_nn47">5.7.2 The SWIG interface file</a></li>
  329 <li><a HREF="#SWIG_nn48">5.7.3 Why use separate interface files?</a></li>
  330 <li><a HREF="#SWIG_nn49">5.7.4 Getting the right header files</a></li>
  331 <li><a HREF="#SWIG_nn50">5.7.5 What to do with main()</a></li>
  332 </ul>
  333 </li>
  334 </ul>
  335 <b><a HREF="#SWIGPlus">6 SWIG and C++</a></b>
  336 <ul>
  337 <li><a HREF="#SWIGPlus_nn2">6.1 Comments on C++ Wrapping</a></li>
  338 <li><a HREF="#SWIGPlus_nn3">6.2 Approach</a></li>
  339 <li><a HREF="#SWIGPlus_nn4">6.3 Supported C++ features</a></li>
  340 <li><a HREF="#SWIGPlus_nn5">6.4 Command line options and compilation</a></li>
  341 <li><a HREF="#SWIGPlus_nn38">6.5 Proxy classes</a>
  342 <ul>
  343 <li><a HREF="#SWIGPlus_nn39">6.5.1 Construction of proxy classes</a></li>
  344 <li><a HREF="#SWIGPlus_nn40">6.5.2 Resource management in proxies</a></li>
  345 <li><a HREF="#SWIGPlus_nn41">6.5.3 Language specific details</a></li>
  346 </ul>
  347 </li>
  348 <li><a HREF="#SWIGPlus_nn6">6.6 Simple C++ wrapping</a>
  349 <ul>
  350 <li><a HREF="#SWIGPlus_nn7">6.6.1 Constructors and destructors</a></li>
  351 <li><a HREF="#SWIGPlus_nn8">6.6.2 Default constructors, copy
  352  constructors and implicit destructors</a></li>
  353 <li><a HREF="#SWIGPlus_nn9">6.6.3 When constructor wrappers aren't
  354  created</a></li>
  355 <li><a HREF="#SWIGPlus_nn10">6.6.4 Copy constructors</a></li>
  356 <li><a HREF="#SWIGPlus_nn11">6.6.5 Member functions</a></li>
  357 <li><a HREF="#SWIGPlus_nn12">6.6.6 Static members</a></li>
  358 <li><a HREF="#SWIGPlus_member_data">6.6.7 Member data</a></li>
  359 </ul>
  360 </li>
  361 <li><a HREF="#SWIGPlus_nn15">6.7 Protection</a></li>
  362 <li><a HREF="#SWIGPlus_nn16">6.8 Enums and constants</a></li>
  363 <li><a HREF="#SWIGPlus_nn17">6.9 Friends</a></li>
  364 <li><a HREF="#SWIGPlus_nn18">6.10 References and pointers</a></li>
  365 <li><a HREF="#SWIGPlus_nn19">6.11 Pass and return by value</a></li>
  366 <li><a HREF="#SWIGPlus_nn20">6.12 Inheritance</a></li>
  367 <li><a HREF="#SWIGPlus_nn21">6.13 A brief discussion of multiple
  368  inheritance, pointers, and type checking</a></li>
  369 <li><a HREF="#SWIGPlus_default_args">6.14 Default arguments</a></li>
  370 <li><a HREF="#SWIGPlus_overloaded_methods">6.15 Overloaded functions and
  371  methods</a>
  372 <ul>
  373 <li><a HREF="#SWIGPlus_nn24">6.15.1 Dispatch function generation</a></li>
  374 <li><a HREF="#SWIGPlus_nn25">6.15.2 Ambiguity in overloading</a></li>
  375 <li><a HREF="#SWIGPlus_ambiguity_resolution_renaming">6.15.3 Renaming
  376  and ambiguity resolution</a></li>
  377 <li><a HREF="#SWIGPlus_nn27">6.15.4 Comments on overloading</a></li>
  378 </ul>
  379 </li>
  380 <li><a HREF="#SWIGPlus_nn28">6.16 Overloaded operators</a></li>
  381 <li><a HREF="#SWIGPlus_class_extension">6.17 Class extension</a>
  382 <ul>
  383 <li><a HREF="#SWIGPlus_replacing_methods">6.17.1 Replacing class methods</a>
  384 </li>
  385 </ul>
  386 </li>
  387 <li><a HREF="#SWIGPlus_nn30">6.18 Templates</a>
  388 <ul>
  389 <li><a HREF="#SWIGPlus_template_directive">6.18.1 The %template
  390  directive</a></li>
  391 <li><a HREF="#SWIGPlus_template_functions">6.18.2 Function templates</a></li>
  392 <li><a HREF="#SWIGPlus_template_classes">6.18.3 Default template
  393  arguments</a></li>
  394 <li><a HREF="#SWIGPlus_template_class_inheritance">6.18.4 Template base
  395  classes</a></li>
  396 <li><a HREF="#SWIGPlus_template_specialization">6.18.5 Template
  397  specialization</a></li>
  398 <li><a HREF="#SWIGPlus_template_member">6.18.6 Member templates</a></li>
  399 <li><a HREF="#SWIGPlus_template_scoping">6.18.7 Scoping and templates</a>
  400 </li>
  401 <li><a HREF="#SWIGPlus_template_more">6.18.8 More on templates</a></li>
  402 </ul>
  403 </li>
  404 <li><a HREF="#SWIGPlus_namespaces">6.19 Namespaces</a>
  405 <ul>
  406 <li><a HREF="#SWIGPlus_nspace">6.19.1 The nspace feature for namespaces</a>
  407 </li>
  408 </ul>
  409 </li>
  410 <li><a HREF="#SWIGPlus_renaming_templated_types_namespaces">6.20
  411  Renaming templated types in namespaces</a></li>
  412 <li><a HREF="#SWIGPlus_exception_specifications">6.21 Exception
  413  specifications</a></li>
  414 <li><a HREF="#SWIGPlus_catches">6.22 Exception handling with %catches</a>
  415 </li>
  416 <li><a HREF="#SWIGPlus_nn33">6.23 Pointers to Members</a></li>
  417 <li><a HREF="#SWIGPlus_smart_pointers">6.24 Smart pointers and
  418  operator-&gt;()</a></li>
  419 <li><a HREF="#SWIGPlus_ref_unref">6.25 C++ reference counted objects -
  420  ref/unref feature</a></li>
  421 <li><a HREF="#SWIGPlus_nn35">6.26 Using declarations and inheritance</a></li>
  422 <li><a HREF="#SWIGPlus_nested_classes">6.27 Nested classes</a></li>
  423 <li><a HREF="#SWIGPlus_const">6.28 A brief rant about const-correctness</a>
  424 </li>
  425 <li><a HREF="#SWIGPlus_target_language_callbacks">6.29 Callbacks to the
  426  target language</a>
  427 <ul>
  428 <li><a HREF="#SWIGPlus_director_classes_introduction">6.29.1
  429  Introduction to director classes</a></li>
  430 <li><a HREF="#SWIGPlus_directors_for_function_pointers">6.29.2 Using
  431  directors and target language callbacks</a></li>
  432 </ul>
  433 </li>
  434 <li><a HREF="#SWIGPlus_nn42">6.30 Where to go for more information</a></li>
  435 </ul>
  436 <b><a HREF="#CPlusPlus11">7 SWIG and C++11</a></b>
  437 <ul>
  438 <li><a HREF="#CPlusPlus11_introduction">7.1 Introduction</a></li>
  439 <li><a HREF="#CPlusPlus11_core_language_changes">7.2 Core language
  440  changes</a>
  441 <ul>
  442 <li><a HREF="#CPlusPlus11_rvalue_reference_and_move_semantics">7.2.1
  443  Rvalue reference and move semantics</a>
  444 <ul>
  445 <li><a HREF="#CPlusPlus11_rvalue_reference_inputs"> Rvalue
  446  reference inputs</a></li>
  447 <li><a HREF="#CPlusPlus11_rvalue_reference_outputs"> Rvalue
  448  reference outputs</a></li>
  449 <li><a HREF="#CPlusPlus11_move_only"> Movable and move-only types
  450  by value</a></li>
  451 </ul>
  452 </li>
  453 <li><a HREF="#CPlusPlus11_generalized_constant_expressions">7.2.2
  454  Generalized constant expressions</a></li>
  455 <li><a HREF="#CPlusPlus11_extern_template">7.2.3 Extern template</a></li>
  456 <li><a HREF="#CPlusPlus11_initializer_lists">7.2.4 Initializer lists</a></li>
  457 <li><a HREF="#CPlusPlus11_uniform_initialization">7.2.5 Uniform
  458  initialization</a></li>
  459 <li><a HREF="#CPlusPlus11_type_inference">7.2.6 Type inference</a></li>
  460 <li><a HREF="#CPlusPlus11_range_based_for_loop">7.2.7 Range-based
  461  for-loop</a></li>
  462 <li><a HREF="#CPlusPlus11_lambda_functions_and_expressions">7.2.8 Lambda
  463  functions and expressions</a></li>
  464 <li><a HREF="#CPlusPlus11_alternate_function_syntax">7.2.9 Alternate
  465  function syntax</a></li>
  466 <li><a HREF="#CPlusPlus11_object_construction_improvement">7.2.10 Object
  467  construction improvement</a></li>
  468 <li><a HREF="#CPlusPlus11_explicit_overrides_final">7.2.11 Explicit
  469  overrides and final</a></li>
  470 <li><a HREF="#CPlusPlus11_null_pointer_constant">7.2.12 Null pointer
  471  constant</a></li>
  472 <li><a HREF="#CPlusPlus11_strongly_typed_enumerations">7.2.13 Strongly
  473  typed enumerations</a></li>
  474 <li><a HREF="#CPlusPlus11_double_angle_brackets">7.2.14 Double angle
  475  brackets</a></li>
  476 <li><a HREF="#CPlusPlus11_explicit_conversion_operators">7.2.15 Explicit
  477  conversion operators</a></li>
  478 <li><a HREF="#CPlusPlus11_alias_templates">7.2.16 Type alias and alias
  479  templates</a></li>
  480 <li><a HREF="#CPlusPlus11_unrestricted_unions">7.2.17 Unrestricted
  481  unions</a></li>
  482 <li><a HREF="#CPlusPlus11_variadic_templates">7.2.18 Variadic templates</a>
  483 </li>
  484 <li><a HREF="#CPlusPlus11_new_char_literals">7.2.19 New character
  485  literals</a></li>
  486 <li><a HREF="#CPlusPlus11_new_string_literals">7.2.20 New string
  487  literals</a></li>
  488 <li><a HREF="#CPlusPlus11_user_defined_literals">7.2.21 User-defined
  489  literals</a></li>
  490 <li><a HREF="#CPlusPlus11_thread_local_storage">7.2.22 Thread-local
  491  storage</a></li>
  492 <li><a HREF="#CPlusPlus11_defaulted_deleted">7.2.23 Explicitly defaulted
  493  functions and deleted functions</a></li>
  494 <li><a HREF="#CPlusPlus11_type_long_long_int">7.2.24 Type long long int</a>
  495 </li>
  496 <li><a HREF="#CPlusPlus11_static_assertions">7.2.25 Static assertions</a>
  497 </li>
  498 <li><a HREF="#CPlusPlus11_sizeof">7.2.26 Allow sizeof to work on members
  499  of classes without an explicit object</a></li>
  500 <li><a HREF="#CPlusPlus11_noexcept">7.2.27 Exception specifications and
  501  noexcept</a></li>
  502 <li><a HREF="#CPlusPlus11_alignment">7.2.28 Control and query object
  503  alignment</a></li>
  504 <li><a HREF="#CPlusPlus11_attributes">7.2.29 Attributes</a></li>
  505 <li><a HREF="#CPlusPlus11_ref_qualifiers">7.2.30 Methods with
  506  ref-qualifiers</a></li>
  507 </ul>
  508 </li>
  509 <li><a HREF="#CPlusPlus11_standard_library_changes">7.3 Standard library
  510  changes</a>
  511 <ul>
  512 <li><a HREF="#CPlusPlus11_threading_facilities">7.3.1 Threading
  513  facilities</a></li>
  514 <li><a HREF="#CPlusPlus11_tuple_types">7.3.2 Tuple types</a></li>
  515 <li><a HREF="#CPlusPlus11_hash_tables">7.3.3 Hash tables</a></li>
  516 <li><a HREF="#CPlusPlus11_regular_expressions">7.3.4 Regular expressions</a>
  517 </li>
  518 <li><a HREF="#CPlusPlus11_general_purpose_smart_pointers">7.3.5
  519  General-purpose smart pointers</a></li>
  520 <li><a HREF="#CPlusPlus11_extensible_random_number_facility">7.3.6
  521  Extensible random number facility</a></li>
  522 <li><a HREF="#CPlusPlus11_wrapper_reference">7.3.7 Wrapper reference</a></li>
  523 <li><a HREF="#CPlusPlus11_polymorphous_wrappers_for_function_objects">
  524 7.3.8 Polymorphic wrappers for function objects</a></li>
  525 <li><a HREF="#CPlusPlus11_type_traits_for_metaprogramming">7.3.9 Type
  526  traits for metaprogramming</a></li>
  527 <li><a HREF="#CPlusPlus11_uniform_method_for_computing_return_type_of_function_objects">
  528 7.3.10 Uniform method for computing return type of function objects</a></li>
  529 </ul>
  530 </li>
  531 </ul>
  532 <b><a HREF="#CPlusPlus14">8 SWIG and C++14</a></b>
  533 <ul>
  534 <li><a HREF="#CPlusPlus14_introduction">8.1 Introduction</a></li>
  535 <li><a HREF="#CPlusPlus14_core_language_changes">8.2 Core language
  536  changes</a>
  537 <ul>
  538 <li><a HREF="#CPlusPlus14_binary_literals">8.2.1 Binary integer literals</a>
  539 </li>
  540 </ul>
  541 </li>
  542 <li><a HREF="#CPlusPlus14_standard_library_changes">8.3 Standard library
  543  changes</a></li>
  544 </ul>
  545 <b><a HREF="#CPlusPlus17">9 SWIG and C++17</a></b>
  546 <ul>
  547 <li><a HREF="#CPlusPlus17_introduction">9.1 Introduction</a></li>
  548 <li><a HREF="#CPlusPlus17_core_language_changes">9.2 Core language
  549  changes</a>
  550 <ul>
  551 <li><a HREF="#CPlusPlus17_nested_namespaces">9.2.1 Nested namespace
  552  definitions</a></li>
  553 <li><a HREF="#CPlusPlus17_u8_char_literals">9.2.2 UTF-8 character
  554  literals</a></li>
  555 <li><a HREF="#CPlusPlus17_hexadecimal_floating_literals">9.2.3
  556  Hexadecimal floating literals</a></li>
  557 </ul>
  558 </li>
  559 <li><a HREF="#CPlusPlus17_standard_library_changes">9.3 Standard library
  560  changes</a></li>
  561 </ul>
  562 <b><a HREF="#CPlusPlus20">10 SWIG and C++20</a></b>
  563 <ul>
  564 <li><a HREF="#CPlusPlus20_introduction">10.1 Introduction</a></li>
  565 <li><a HREF="#CPlusPlus20_core_language_changes">10.2 Core language
  566  changes</a>
  567 <ul>
  568 <li><a HREF="#CPlusPlus20_spaceship_operator">10.2.1 Spaceship operator</a>
  569 </li>
  570 <li><a HREF="#CPlusPlus20_lambda_templates">10.2.2 Lambda templates</a></li>
  571 </ul>
  572 </li>
  573 <li><a HREF="#CPlusPlus20_standard_library_changes">10.3 Standard
  574  library changes</a></li>
  575 </ul>
  576 <b><a HREF="#Preprocessor">11 Preprocessing</a></b>
  577 <ul>
  578 <li><a HREF="#Preprocessor_nn2">11.1 File inclusion</a></li>
  579 <li><a HREF="#Preprocessor_nn3">11.2 File imports</a></li>
  580 <li><a HREF="#Preprocessor_condition_compilation">11.3 Conditional
  581  Compilation</a></li>
  582 <li><a HREF="#Preprocessor_nn5">11.4 Macro Expansion</a></li>
  583 <li><a HREF="#Preprocessor_nn6">11.5 SWIG Macros</a></li>
  584 <li><a HREF="#Preprocessor_nn7">11.6 C99 and GNU Extensions</a></li>
  585 <li><a HREF="#Preprocessor_delimiters">11.7 Preprocessing and delimiters</a>
  586 <ul>
  587 <li><a HREF="#Preprocessor_nn8">11.7.1 Preprocessing and %{ ... %} &amp; &quot;
  588  ... &quot; delimiters</a></li>
  589 <li><a HREF="#Preprocessor_nn9">11.7.2 Preprocessing and { ... }
  590  delimiters</a></li>
  591 </ul>
  592 </li>
  593 <li><a HREF="#Preprocessor_typemap_delimiters">11.8 Preprocessor and
  594  Typemaps</a></li>
  595 <li><a HREF="#Preprocessor_nn10">11.9 Viewing preprocessor output</a></li>
  596 <li><a HREF="#Preprocessor_warning_error">11.10 The #error and #warning
  597  directives</a></li>
  598 </ul>
  599 <b><a HREF="#Library">12 SWIG library</a></b>
  600 <ul>
  601 <li><a HREF="#Library_nn2">12.1 The %include directive and library
  602  search path</a></li>
  603 <li><a HREF="#Library_nn3">12.2 C arrays and pointers</a>
  604 <ul>
  605 <li><a HREF="#Library_argcargv">12.2.1 argcargv.i</a></li>
  606 <li><a HREF="#Library_nn4">12.2.2 cpointer.i</a></li>
  607 <li><a HREF="#Library_carrays">12.2.3 carrays.i</a></li>
  608 <li><a HREF="#Library_nn6">12.2.4 cmalloc.i</a></li>
  609 <li><a HREF="#Library_nn7">12.2.5 cdata.i</a></li>
  610 </ul>
  611 </li>
  612 <li><a HREF="#Library_nn8">12.3 C string handling</a>
  613 <ul>
  614 <li><a HREF="#Library_nn9">12.3.1 Default string handling</a></li>
  615 <li><a HREF="#Library_nn10">12.3.2 Passing binary data</a></li>
  616 <li><a HREF="#Library_nn11">12.3.3 Using %newobject to release memory</a>
  617 </li>
  618 <li><a HREF="#Library_nn12">12.3.4 cstring.i</a></li>
  619 </ul>
  620 </li>
  621 <li><a HREF="#Library_stl_cpp_library">12.4 STL/C++ library</a>
  622 <ul>
  623 <li><a HREF="#Library_std_string">12.4.1 std::string</a></li>
  624 <li><a HREF="#Library_std_vector">12.4.2 std::vector</a></li>
  625 <li><a HREF="#Library_stl_exceptions">12.4.3 STL exceptions</a></li>
  626 <li><a HREF="#Library_std_shared_ptr">12.4.4 shared_ptr smart pointer</a>
  627 <ul>
  628 <li><a HREF="#Library_shared_ptr_basics"> shared_ptr basics</a></li>
  629 <li><a HREF="#Library_shared_ptr_inheritance"> shared_ptr and
  630  inheritance</a></li>
  631 <li><a HREF="#Library_shared_ptr_overloading"> shared_ptr and
  632  method overloading</a></li>
  633 <li><a HREF="#Library_shared_ptr_templates"> shared_ptr and
  634  templates</a></li>
  635 <li><a HREF="#Library_shared_ptr_directors"> shared_ptr and
  636  directors</a></li>
  637 </ul>
  638 </li>
  639 <li><a HREF="#Library_std_unique_ptr">12.4.5 unique_ptr smart pointer</a>
  640 </li>
  641 <li><a HREF="#Library_std_auto_ptr">12.4.6 auto_ptr smart pointer</a></li>
  642 </ul>
  643 </li>
  644 <li><a HREF="#Library_nn16">12.5 Utility Libraries</a>
  645 <ul>
  646 <li><a HREF="#Library_nn17">12.5.1 exception.i</a></li>
  647 <li><a HREF="#Library_attributes">12.5.2 attribute.i</a>
  648 <ul>
  649 <li><a HREF="#Library_attribute_templates"> %attribute and C++
  650  templates</a></li>
  651 </ul>
  652 </li>
  653 </ul>
  654 </li>
  655 </ul>
  656 <b><a HREF="#Arguments">13 Argument Handling</a></b>
  657 <ul>
  658 <li><a HREF="#Arguments_nn2">13.1 The typemaps.i library</a>
  659 <ul>
  660 <li><a HREF="#Arguments_nn3">13.1.1 Introduction</a></li>
  661 <li><a HREF="#Arguments_nn4">13.1.2 Input parameters</a></li>
  662 <li><a HREF="#Arguments_nn5">13.1.3 Output parameters</a></li>
  663 <li><a HREF="#Arguments_nn6">13.1.4 Input/Output parameters</a></li>
  664 <li><a HREF="#Arguments_nn7">13.1.5 Using different names</a></li>
  665 </ul>
  666 </li>
  667 <li><a HREF="#Arguments_nn8">13.2 Applying constraints to input values</a>
  668 <ul>
  669 <li><a HREF="#Arguments_nn9">13.2.1 Simple constraint example</a></li>
  670 <li><a HREF="#Arguments_nn10">13.2.2 Constraint methods</a></li>
  671 <li><a HREF="#Arguments_nn11">13.2.3 Applying constraints to new
  672  datatypes</a></li>
  673 </ul>
  674 </li>
  675 </ul>
  676 <b><a HREF="#Typemaps">14 Typemaps</a></b>
  677 <ul>
  678 <li><a HREF="#Typemaps_nn2">14.1 Introduction</a>
  679 <ul>
  680 <li><a HREF="#Typemaps_nn3">14.1.1 Type conversion</a></li>
  681 <li><a HREF="#Typemaps_nn4">14.1.2 Typemaps</a></li>
  682 <li><a HREF="#Typemaps_nn5">14.1.3 Pattern matching</a></li>
  683 <li><a HREF="#Typemaps_nn6">14.1.4 Reusing typemaps</a></li>
  684 <li><a HREF="#Typemaps_nn7">14.1.5 What can be done with typemaps?</a></li>
  685 <li><a HREF="#Typemaps_nn8">14.1.6 What can't be done with typemaps?</a></li>
  686 <li><a HREF="#Typemaps_aspects">14.1.7 Similarities to Aspect Oriented
  687  Programming</a></li>
  688 <li><a HREF="#Typemaps_nn9">14.1.8 The rest of this chapter</a></li>
  689 </ul>
  690 </li>
  691 <li><a HREF="#Typemaps_nn10">14.2 Typemap specifications</a>
  692 <ul>
  693 <li><a HREF="#Typemaps_defining">14.2.1 Defining a typemap</a></li>
  694 <li><a HREF="#Typemaps_nn12">14.2.2 Typemap scope</a></li>
  695 <li><a HREF="#Typemaps_nn13">14.2.3 Copying a typemap</a></li>
  696 <li><a HREF="#Typemaps_nn14">14.2.4 Deleting a typemap</a></li>
  697 <li><a HREF="#Typemaps_nn15">14.2.5 Placement of typemaps</a></li>
  698 </ul>
  699 </li>
  700 <li><a HREF="#Typemaps_pattern_matching">14.3 Pattern matching rules</a>
  701 <ul>
  702 <li><a HREF="#Typemaps_nn17">14.3.1 Basic matching rules</a></li>
  703 <li><a HREF="#Typemaps_typedef_reductions">14.3.2 Typedef reductions
  704  matching</a></li>
  705 <li><a HREF="#Typemaps_nn19">14.3.3 Default typemap matching rules</a></li>
  706 <li><a HREF="#Typemaps_multi_argument_typemaps_patterns">14.3.4
  707  Multi-arguments typemaps</a></li>
  708 <li><a HREF="#Typemaps_matching_template_comparison">14.3.5 Matching
  709  rules compared to C++ templates</a></li>
  710 <li><a HREF="#Typemaps_debugging_search">14.3.6 Debugging typemap
  711  pattern matching</a></li>
  712 </ul>
  713 </li>
  714 <li><a HREF="#Typemaps_nn21">14.4 Code generation rules</a>
  715 <ul>
  716 <li><a HREF="#Typemaps_nn22">14.4.1 Scope</a></li>
  717 <li><a HREF="#Typemaps_nn23">14.4.2 Declaring new local variables</a></li>
  718 <li><a HREF="#Typemaps_special_variables">14.4.3 Special variables</a></li>
  719 <li><a HREF="#Typemaps_special_variable_macros">14.4.4 Special variable
  720  macros</a>
  721 <ul>
  722 <li><a HREF="#Typemaps_special_macro_descriptor">
  723  $descriptor(type)</a></li>
  724 <li><a HREF="#Typemaps_special_macro_typemap"> $typemap(method,
  725  typepattern)</a></li>
  726 <li><a HREF="#Typemaps_special_macro_typemap_attribute">
  727  $typemap(method:attribute, typepattern)</a></li>
  728 </ul>
  729 </li>
  730 <li><a HREF="#Typemaps_special_variable_attributes">14.4.5 Special
  731  variables and typemap attributes</a></li>
  732 <li><a HREF="#Typemaps_special_variables_and_macros">14.4.6 Special
  733  variables combined with special variable macros</a></li>
  734 </ul>
  735 </li>
  736 <li><a HREF="#Typemaps_nn25">14.5 Common typemap methods</a>
  737 <ul>
  738 <li><a HREF="#Typemaps_nn26">14.5.1 &quot;in&quot; typemap</a></li>
  739 <li><a HREF="#Typemaps_nn27">14.5.2 &quot;typecheck&quot; typemap</a></li>
  740 <li><a HREF="#Typemaps_nn28">14.5.3 &quot;out&quot; typemap</a></li>
  741 <li><a HREF="#Typemaps_nn29">14.5.4 &quot;arginit&quot; typemap</a></li>
  742 <li><a HREF="#Typemaps_nn30">14.5.5 &quot;default&quot; typemap</a></li>
  743 <li><a HREF="#Typemaps_nn31">14.5.6 &quot;check&quot; typemap</a></li>
  744 <li><a HREF="#Typemaps_nn32">14.5.7 &quot;argout&quot; typemap</a></li>
  745 <li><a HREF="#Typemaps_nn33">14.5.8 &quot;freearg&quot; typemap</a></li>
  746 <li><a HREF="#Typemaps_nn34">14.5.9 &quot;newfree&quot; typemap</a></li>
  747 <li><a HREF="#Typemaps_ret">14.5.10 &quot;ret&quot; typemap</a></li>
  748 <li><a HREF="#Typemaps_nn35">14.5.11 &quot;memberin&quot; typemap</a></li>
  749 <li><a HREF="#Typemaps_nn36">14.5.12 &quot;varin&quot; typemap</a></li>
  750 <li><a HREF="#Typemaps_nn37">14.5.13 &quot;varout&quot; typemap</a></li>
  751 <li><a HREF="#Typemaps_throws_typemap">14.5.14 &quot;throws&quot; typemap</a></li>
  752 </ul>
  753 </li>
  754 <li><a HREF="#Typemaps_nn39">14.6 Some typemap examples</a>
  755 <ul>
  756 <li><a HREF="#Typemaps_nn40">14.6.1 Typemaps for arrays</a></li>
  757 <li><a HREF="#Typemaps_nn41">14.6.2 Implementing constraints with
  758  typemaps</a></li>
  759 </ul>
  760 </li>
  761 <li><a HREF="#Typemaps_nn43">14.7 Typemaps for multiple target languages</a>
  762 </li>
  763 <li><a HREF="#Typemaps_optimal">14.8 Optimal code generation when
  764  returning by value</a></li>
  765 <li><a HREF="#Typemaps_multi_argument_typemaps">14.9 Multi-argument
  766  typemaps</a></li>
  767 <li><a HREF="#Typemaps_warnings">14.10 Typemap warnings</a></li>
  768 <li><a HREF="#Typemaps_fragments">14.11 Typemap fragments</a>
  769 <ul>
  770 <li><a HREF="#Typemaps_fragment_type_specialization">14.11.1 Fragment
  771  type specialization</a></li>
  772 <li><a HREF="#Typemaps_automatic_specialization">14.11.2 Fragments and
  773  automatic typemap specialization</a></li>
  774 </ul>
  775 </li>
  776 <li><a HREF="#Typemaps_runtime_type_checker">14.12 The run-time type
  777  checker</a>
  778 <ul>
  779 <li><a HREF="#Typemaps_nn45">14.12.1 Implementation</a></li>
  780 <li><a HREF="#Typemaps_runtime_type_checker_usage">14.12.2 Usage</a></li>
  781 </ul>
  782 </li>
  783 <li><a HREF="#Typemaps_overloading">14.13 Typemaps and overloading</a>
  784 <ul>
  785 <li><a HREF="#Typemaps_typecheck_pointer">14.13.1 SWIG_TYPECHECK_POINTER
  786  precedence level and the typecheck typemap</a></li>
  787 </ul>
  788 </li>
  789 <li><a HREF="#Typemaps_nn48">14.14 More about %apply and %clear</a></li>
  790 <li><a HREF="#Typemaps_nn47">14.15 Passing data between typemaps</a></li>
  791 <li><a HREF="#Typemaps_nn52">14.16 C++ &quot;this&quot; pointer</a></li>
  792 <li><a HREF="#Typemaps_nn51">14.17 Where to go for more information?</a></li>
  793 </ul>
  794 <b><a HREF="#Customization">15 Customization Features</a></b>
  795 <ul>
  796 <li><a HREF="#Customization_exception">15.1 Exception handling with
  797  %exception</a>
  798 <ul>
  799 <li><a HREF="#Customization_nn3">15.1.1 Handling exceptions in C code</a>
  800 </li>
  801 <li><a HREF="#Customization_nn4">15.1.2 Exception handling with
  802  longjmp()</a></li>
  803 <li><a HREF="#Customization_nn5">15.1.3 Handling C++ exceptions</a></li>
  804 <li><a HREF="#Customization_allowexcept">15.1.4 Exception handlers for
  805  variables</a></li>
  806 <li><a HREF="#Customization_nn6">15.1.5 Defining different exception
  807  handlers</a></li>
  808 <li><a HREF="#Customization_exception_special_variables">15.1.6 Special
  809  variables for %exception</a></li>
  810 <li><a HREF="#Customization_nn7">15.1.7 Using The SWIG exception library</a>
  811 </li>
  812 </ul>
  813 </li>
  814 <li><a HREF="#Customization_ownership">15.2 Object ownership and
  815  %newobject</a></li>
  816 <li><a HREF="#Customization_features">15.3 Features and the %feature
  817  directive</a>
  818 <ul>
  819 <li><a HREF="#Customization_feature_attributes">15.3.1 Feature
  820  attributes</a></li>
  821 <li><a HREF="#Customization_feature_flags">15.3.2 Feature flags</a></li>
  822 <li><a HREF="#Customization_clearing_features">15.3.3 Clearing features</a>
  823 </li>
  824 <li><a HREF="#Customization_features_default_args">15.3.4 Features and
  825  default arguments</a></li>
  826 <li><a HREF="#Customization_features_example">15.3.5 Feature example</a></li>
  827 </ul>
  828 </li>
  829 </ul>
  830 <b><a HREF="#Contract">16 Contracts</a></b>
  831 <ul>
  832 <li><a HREF="#Contract_nn2">16.1 The %contract directive</a></li>
  833 <li><a HREF="#Contract_nn3">16.2 %contract and classes</a></li>
  834 <li><a HREF="#Contract_nn4">16.3 Constant aggregation and
  835  %aggregate_check</a></li>
  836 <li><a HREF="#Contract_nn5">16.4 Notes</a></li>
  837 </ul>
  838 <b><a HREF="#Varargs">17 Variable Length Arguments</a></b>
  839 <ul>
  840 <li><a HREF="#Varargs_nn2">17.1 Introduction</a></li>
  841 <li><a HREF="#Varargs_nn3">17.2 The Problem</a></li>
  842 <li><a HREF="#Varargs_nn4">17.3 Default varargs support</a></li>
  843 <li><a HREF="#Varargs_nn5">17.4 Argument replacement using %varargs</a></li>
  844 <li><a HREF="#Varargs_nn6">17.5 Varargs and typemaps</a></li>
  845 <li><a HREF="#Varargs_nn7">17.6 Varargs wrapping with libffi</a></li>
  846 <li><a HREF="#Varargs_nn8">17.7 Wrapping of va_list</a></li>
  847 <li><a HREF="#Varargs_nn9">17.8 C++ Issues</a></li>
  848 <li><a HREF="#Varargs_nn10">17.9 Discussion</a></li>
  849 </ul>
  850 <b><a HREF="#Doxygen">18 SWIG and Doxygen Translation</a></b>
  851 <ul>
  852 <li><a HREF="#Doxygen_translation_overview">18.1 Doxygen translation
  853  overview</a></li>
  854 <li><a HREF="#Doxygen_file_preparation">18.2 Preparations</a>
  855 <ul>
  856 <li><a HREF="#Doxygen_running_swig">18.2.1 Enabling Doxygen translation</a>
  857 </li>
  858 <li><a HREF="#Doxygen_features">18.2.2 Doxygen-specific %feature
  859  directives</a>
  860 <ul>
  861 <li><a HREF="#Doxygen_notranslate"> doxygen:notranslate</a></li>
  862 <li><a HREF="#Doxygen_alias"> doxygen:alias:&lt;command-name&gt;</a></li>
  863 <li><a HREF="#Doxygen_ignore"> doxygen:ignore:&lt;command-name&gt;</a></li>
  864 <li><a HREF="#Doxygen_nolinktranslate"> doxygen:nolinktranslate</a>
  865 </li>
  866 <li><a HREF="#Doxygen_nostripparams"> doxygen:nostripparams</a></li>
  867 </ul>
  868 </li>
  869 <li><a HREF="#Doxygen_additional_options">18.2.3 Additional command line
  870  options</a></li>
  871 </ul>
  872 </li>
  873 <li><a HREF="#Doxygen_to_javadoc">18.3 Doxygen to Javadoc</a>
  874 <ul>
  875 <li><a HREF="#Doxygen_basic_example">18.3.1 Basic example</a></li>
  876 <li><a HREF="#Doxygen_javadoc_tags">18.3.2 Javadoc tags</a></li>
  877 <li><a HREF="#Doxygen_unsupported_tags">18.3.3 Unsupported tags</a></li>
  878 <li><a HREF="#Doxygen_further_details">18.3.4 Further details</a></li>
  879 </ul>
  880 </li>
  881 <li><a HREF="#Doxygen_to_pydoc">18.4 Doxygen to Pydoc</a>
  882 <ul>
  883 <li><a HREF="#Doxygen_python_basic_example">18.4.1 Basic example</a></li>
  884 <li><a HREF="#Doxygen_pydoc_tags">18.4.2 Pydoc translator</a></li>
  885 <li><a HREF="#Doxygen_python_unsupported_tags">18.4.3 Unsupported tags</a>
  886 </li>
  887 <li><a HREF="#Doxygen_python_further_details">18.4.4 Further details</a></li>
  888 </ul>
  889 </li>
  890 <li><a HREF="#Doxygen_troubleshooting">18.5 Troubleshooting</a>
  891 <ul>
  892 <li><a HREF="#troubleshooting_ifndef">18.5.1 Problem with conditional
  893  compilation</a></li>
  894 </ul>
  895 </li>
  896 <li><a HREF="#Doxygen_developer_details">18.6 Developer information</a>
  897 <ul>
  898 <li><a HREF="#Doxygen_translator_design">18.6.1 Doxygen translator
  899  design</a></li>
  900 <li><a HREF="#Doxygen_debugging_commands">18.6.2 Debugging the Doxygen
  901  parser and translator</a></li>
  902 <li><a HREF="#Doxygen_tests">18.6.3 Tests</a></li>
  903 </ul>
  904 </li>
  905 <li><a HREF="#Doxygen_language_extension">18.7 Extending to other
  906  languages</a></li>
  907 </ul>
  908 <b><a HREF="#Warnings">19 Warning Messages</a></b>
  909 <ul>
  910 <li><a HREF="#Warnings_nn2">19.1 Introduction</a></li>
  911 <li><a HREF="#Warnings_suppression">19.2 Warning message suppression</a></li>
  912 <li><a HREF="#Warnings_nn4">19.3 Enabling extra warnings</a></li>
  913 <li><a HREF="#Warnings_nn5">19.4 Issuing a warning message</a></li>
  914 <li><a HREF="#Warnings_symbolic_symbols">19.5 Symbolic symbols</a></li>
  915 <li><a HREF="#Warnings_nn6">19.6 Commentary</a></li>
  916 <li><a HREF="#Warnings_nn7">19.7 Warnings as errors</a></li>
  917 <li><a HREF="#Warnings_nn8">19.8 Message output format</a></li>
  918 <li><a HREF="#Warnings_nn9">19.9 Warning number reference</a>
  919 <ul>
  920 <li><a HREF="#Warnings_nn10">19.9.1 Deprecated features (100-199)</a></li>
  921 <li><a HREF="#Warnings_nn11">19.9.2 Preprocessor (200-299)</a></li>
  922 <li><a HREF="#Warnings_nn12">19.9.3 C/C++ Parser (300-399)</a></li>
  923 <li><a HREF="#Warnings_nn13">19.9.4 Types and typemaps (400-499)</a></li>
  924 <li><a HREF="#Warnings_nn14">19.9.5 Code generation (500-559)</a></li>
  925 <li><a HREF="#Warnings_doxygen">19.9.6 Doxygen comments (560-599)</a></li>
  926 <li><a HREF="#Warnings_nn15">19.9.7 Language module specific (700-899)</a>
  927 </li>
  928 <li><a HREF="#Warnings_nn16">19.9.8 User defined (900-999)</a></li>
  929 </ul>
  930 </li>
  931 <li><a HREF="#Warnings_nn17">19.10 History</a></li>
  932 </ul>
  933 <b><a HREF="#Modules">20 Working with Modules</a></b>
  934 <ul>
  935 <li><a HREF="#Modules_introduction">20.1 Modules Introduction</a></li>
  936 <li><a HREF="#Modules_nn1">20.2 Basics</a></li>
  937 <li><a HREF="#Modules_nn2">20.3 The SWIG runtime code</a></li>
  938 <li><a HREF="#Modules_external_run_time">20.4 External access to the
  939  runtime</a></li>
  940 <li><a HREF="#Modules_nn4">20.5 A word of caution about static libraries</a>
  941 </li>
  942 <li><a HREF="#Modules_nn5">20.6 References</a></li>
  943 <li><a HREF="#Modules_nn6">20.7 Reducing the wrapper file size</a></li>
  944 </ul>
  945 <b><a HREF="#CCache">21 Using SWIG with ccache - ccache-swig(1) manpage</a>
  946 </b>
  947 <ul>
  948 <li><a HREF="#CCache_nn2">21.1 NAME</a></li>
  949 <li><a HREF="#CCache_nn3">21.2 SYNOPSIS</a></li>
  950 <li><a HREF="#CCache_nn4">21.3 DESCRIPTION</a></li>
  951 <li><a HREF="#CCache_nn5">21.4 OPTIONS SUMMARY</a></li>
  952 <li><a HREF="#CCache_nn6">21.5 OPTIONS</a></li>
  953 <li><a HREF="#CCache_nn7">21.6 INSTALLATION</a></li>
  954 <li><a HREF="#CCache_nn8">21.7 EXTRA OPTIONS</a></li>
  955 <li><a HREF="#CCache_nn9">21.8 ENVIRONMENT VARIABLES</a></li>
  956 <li><a HREF="#CCache_nn10">21.9 CACHE SIZE MANAGEMENT</a></li>
  957 <li><a HREF="#CCache_nn11">21.10 CACHE COMPRESSION</a></li>
  958 <li><a HREF="#CCache_nn12">21.11 HOW IT WORKS</a></li>
  959 <li><a HREF="#CCache_nn13">21.12 USING CCACHE WITH DISTCC</a></li>
  960 <li><a HREF="#CCache_nn14">21.13 SHARING A CACHE</a></li>
  961 <li><a HREF="#CCache_nn15">21.14 HISTORY</a></li>
  962 <li><a HREF="#CCache_nn16">21.15 DIFFERENCES FROM COMPILERCACHE</a></li>
  963 <li><a HREF="#CCache_nn17">21.16 CREDITS</a></li>
  964 <li><a HREF="#CCache_nn18">21.17 AUTHOR</a></li>
  965 </ul>
  966 <b><a HREF="#Android">22 SWIG and Android</a></b>
  967 <ul>
  968 <li><a HREF="#Android_overview">22.1 Overview</a></li>
  969 <li><a HREF="#Android_examples">22.2 Android examples</a>
  970 <ul>
  971 <li><a HREF="#Android_examples_intro">22.2.1 Examples introduction</a></li>
  972 <li><a HREF="#Android_example_simple">22.2.2 Simple C example</a></li>
  973 <li><a HREF="#Android_example_class">22.2.3 C++ class example</a></li>
  974 <li><a HREF="#Android_examples_other">22.2.4 Other examples</a></li>
  975 </ul>
  976 </li>
  977 <li><a HREF="#Android_stl">22.3 C++ STL</a></li>
  978 </ul>
  979 <b><a HREF="#CSharp">23 SWIG and C#</a></b>
  980 <ul>
  981 <li><a HREF="#CSharp_introduction">23.1 Introduction</a>
  982 <ul>
  983 <li><a HREF="#CSharp_introduction_swig2_compatibility">23.1.1 SWIG 2
  984  Compatibility</a></li>
  985 <li><a HREF="#CSharp_commandline">23.1.2 Additional command line options</a>
  986 </li>
  987 </ul>
  988 </li>
  989 <li><a HREF="#CSharp_differences_java">23.2 Differences to the Java
  990  module</a></li>
  991 <li><a HREF="#CSharp_void_pointers">23.3 Void pointers</a></li>
  992 <li><a HREF="#CSharp_arrays">23.4 C# Arrays</a>
  993 <ul>
  994 <li><a HREF="#CSharp_arrays_swig_library">23.4.1 The SWIG C arrays
  995  library</a></li>
  996 <li><a HREF="#CSharp_arrays_pinvoke_default_array_marshalling">23.4.2
  997  Managed arrays using P/Invoke default array marshalling</a></li>
  998 <li><a HREF="#CSharp_arrays_pinning">23.4.3 Managed arrays using pinning</a>
  999 </li>
 1000 </ul>
 1001 </li>
 1002 <li><a HREF="#CSharp_exceptions">23.5 C# Exceptions</a>
 1003 <ul>
 1004 <li><a HREF="#CSharp_exception_example_check_typemap">23.5.1 C#
 1005  exception example using &quot;check&quot; typemap</a></li>
 1006 <li><a HREF="#CSharp_exception_example_percent_exception">23.5.2 C#
 1007  exception example using %exception</a></li>
 1008 <li><a HREF="#CSharp_exception_example_exception_specifications">23.5.3
 1009  C# exception example using exception specifications</a></li>
 1010 <li><a HREF="#CSharp_custom_application_exception">23.5.4 Custom C#
 1011  ApplicationException example</a></li>
 1012 </ul>
 1013 </li>
 1014 <li><a HREF="#CSharp_directors">23.6 C# Directors</a>
 1015 <ul>
 1016 <li><a HREF="#CSharp_directors_example">23.6.1 Directors example</a></li>
 1017 <li><a HREF="#CSharp_directors_implementation">23.6.2 Directors
 1018  implementation</a></li>
 1019 <li><a HREF="#CSharp_director_caveats">23.6.3 Director caveats</a></li>
 1020 </ul>
 1021 </li>
 1022 <li><a HREF="#CSharp_multiple_modules">23.7 Multiple modules</a></li>
 1023 <li><a HREF="#CSharp_typemap_examples">23.8 C# Typemap examples</a>
 1024 <ul>
 1025 <li><a HREF="#CSharp_memory_management_member_variables">23.8.1 Memory
 1026  management when returning references to member variables</a></li>
 1027 <li><a HREF="#CSharp_memory_management_objects">23.8.2 Memory management
 1028  for objects passed to the C++ layer</a></li>
 1029 <li><a HREF="#CSharp_date_marshalling">23.8.3 Date marshalling using the
 1030  csin typemap and associated attributes</a></li>
 1031 <li><a HREF="#CSharp_date_properties">23.8.4 A date example
 1032  demonstrating marshalling of C# properties</a></li>
 1033 <li><a HREF="#CSharp_date_pre_post_directors">23.8.5 Date example
 1034  demonstrating the 'pre' and 'post' typemap attributes for directors</a></li>
 1035 <li><a HREF="#CSharp_partial_classes">23.8.6 Turning proxy classes into
 1036  partial classes</a></li>
 1037 <li><a HREF="#CSharp_sealed_proxy_class">23.8.7 Turning proxy classes
 1038  into sealed classes</a></li>
 1039 <li><a HREF="#CSharp_extending_proxy_class">23.8.8 Extending proxy
 1040  classes with additional C# code</a></li>
 1041 <li><a HREF="#CSharp_enum_underlying_type">23.8.9 Underlying type for
 1042  enums</a></li>
 1043 </ul>
 1044 </li>
 1045 </ul>
 1046 <b><a HREF="#D">24 SWIG and D</a></b>
 1047 <ul>
 1048 <li><a HREF="#D_introduction">24.1 Introduction</a></li>
 1049 <li><a HREF="#D_command_line_invocation">24.2 Command line invocation</a>
 1050 </li>
 1051 <li><a HREF="#D_typemaps">24.3 Typemaps</a>
 1052 <ul>
 1053 <li><a HREF="#D_typemap_name_comparison">24.3.1 C# &lt;-&gt; D name comparison</a>
 1054 </li>
 1055 <li><a HREF="#D_ctype_imtype_dtype">24.3.2 ctype, imtype, dtype</a></li>
 1056 <li><a HREF="#D_in_out_directorin_direcetorout">24.3.3 in, out,
 1057  directorin, directorout</a></li>
 1058 <li><a HREF="#D_din_dout_ddirectorin_ddirectorout">24.3.4 din, dout,
 1059  ddirectorin, ddirectorout</a></li>
 1060 <li><a HREF="#D_typecheck_typemaps">24.3.5 typecheck typemaps</a></li>
 1061 <li><a HREF="#D_code_injection_typemaps">24.3.6 Code injection typemaps</a>
 1062 </li>
 1063 <li><a HREF="#D_special_variables">24.3.7 Special variable macros</a></li>
 1064 </ul>
 1065 </li>
 1066 <li><a HREF="#D_features">24.4 D and %feature</a></li>
 1067 <li><a HREF="#D_pragmas">24.5 Pragmas</a></li>
 1068 <li><a HREF="#D_exceptions">24.6 D Exceptions</a></li>
 1069 <li><a HREF="#D_directors">24.7 D Directors</a></li>
 1070 <li><a HREF="#D_other_features">24.8 Other features</a>
 1071 <ul>
 1072 <li><a HREF="#D_nspace">24.8.1 Extended namespace support (nspace)</a></li>
 1073 <li><a HREF="#D_native_pointer_support">24.8.2 Native pointer support</a>
 1074 </li>
 1075 <li><a HREF="#D_operator_overloading">24.8.3 Operator overloading</a></li>
 1076 <li><a HREF="#D_test_suite">24.8.4 Running the test-suite</a></li>
 1077 </ul>
 1078 </li>
 1079 <li><a HREF="#D_typemap_examples">24.9 D Typemap examples</a></li>
 1080 <li><a HREF="#D_planned_features">24.10 Work in progress and planned
 1081  features</a></li>
 1082 </ul>
 1083 <b><a HREF="#Go">25 SWIG and Go</a></b>
 1084 <ul>
 1085 <li><a HREF="#Go_overview">25.1 Overview</a></li>
 1086 <li><a HREF="#Go_examples">25.2 Examples</a></li>
 1087 <li><a HREF="#Go_running_swig">25.3 Running SWIG with Go</a>
 1088 <ul>
 1089 <li><a HREF="#Go_commandline">25.3.1 Go-specific Commandline Options</a></li>
 1090 <li><a HREF="#Go_outputs">25.3.2 Generated Wrapper Files</a></li>
 1091 </ul>
 1092 </li>
 1093 <li><a HREF="#Go_basic_tour">25.4 A tour of basic C/C++ wrapping</a>
 1094 <ul>
 1095 <li><a HREF="#Go_package">25.4.1 Go Package Name</a></li>
 1096 <li><a HREF="#Go_names">25.4.2 Go Names</a></li>
 1097 <li><a HREF="#Go_constants">25.4.3 Go Constants</a></li>
 1098 <li><a HREF="#Go_enumerations">25.4.4 Go Enumerations</a></li>
 1099 <li><a HREF="#Go_classes">25.4.5 Go Classes</a>
 1100 <ul>
 1101 <li><a HREF="#Go_class_memory"> Go Class Memory Management</a></li>
 1102 <li><a HREF="#Go_class_inheritance"> Go Class Inheritance</a></li>
 1103 </ul>
 1104 </li>
 1105 <li><a HREF="#Go_templates">25.4.6 Go Templates</a></li>
 1106 <li><a HREF="#Go_threads">25.4.7 Go and C/C++ Threads</a></li>
 1107 <li><a HREF="#Go_exceptions">25.4.8 Go and C++ Exceptions</a></li>
 1108 <li><a HREF="#Go_director_classes">25.4.9 Go Director Classes</a>
 1109 <ul>
 1110 <li><a HREF="#Go_director_example_cpp_code"> Example C++ code</a>
 1111 </li>
 1112 <li><a HREF="#Go_director_enable"> Enable director feature</a></li>
 1113 <li><a HREF="#Go_director_ctor_dtor"> Constructor and destructor</a>
 1114 </li>
 1115 <li><a HREF="#Go_director_overriding"> Override virtual methods</a>
 1116 </li>
 1117 <li><a HREF="#Go_director_base_methods"> Call base methods</a></li>
 1118 <li><a HREF="#Go_director_subclass"> Subclass via embedding</a></li>
 1119 <li><a HREF="#Go_director_finalizer"> Memory management with
 1120  runtime.SetFinalizer</a></li>
 1121 <li><a HREF="#Go_director_foobargo_class"> Complete FooBarGo
 1122  example class</a></li>
 1123 </ul>
 1124 </li>
 1125 <li><a HREF="#Go_primitive_type_mappings">25.4.10 Default Go primitive
 1126  type mappings</a></li>
 1127 <li><a HREF="#Go_output_arguments">25.4.11 Output arguments</a></li>
 1128 <li><a HREF="#Go_adding_additional_code">25.4.12 Adding additional go
 1129  code</a></li>
 1130 <li><a HREF="#Go_typemaps">25.4.13 Go typemaps</a></li>
 1131 </ul>
 1132 </li>
 1133 </ul>
 1134 <b><a HREF="#Guile">26 SWIG and Guile</a></b>
 1135 <ul>
 1136 <li><a HREF="#Guile_nn1">26.1 Supported Guile Versions</a></li>
 1137 <li><a HREF="#Guile_nn2">26.2 Meaning of &quot;Module&quot;</a></li>
 1138 <li><a HREF="#Guile_nn3">26.3 Old GH Guile API</a></li>
 1139 <li><a HREF="#Guile_nn4">26.4 Linkage</a>
 1140 <ul>
 1141 <li><a HREF="#Guile_nn5">26.4.1 Simple Linkage</a></li>
 1142 <li><a HREF="#Guile_nn6">26.4.2 Passive Linkage</a></li>
 1143 <li><a HREF="#Guile_nn7">26.4.3 Native Guile Module Linkage</a></li>
 1144 <li><a HREF="#Guile_nn8">26.4.4 Old Auto-Loading Guile Module Linkage</a>
 1145 </li>
 1146 <li><a HREF="#Guile_nn9">26.4.5 Hobbit4D Linkage</a></li>
 1147 </ul>
 1148 </li>
 1149 <li><a HREF="#Guile_nn10">26.5 Underscore Folding</a></li>
 1150 <li><a HREF="#Guile_nn11">26.6 Typemaps</a></li>
 1151 <li><a HREF="#Guile_nn12">26.7 Representation of pointers as smobs</a>
 1152 <ul>
 1153 <li><a HREF="#Guile_nn14">26.7.1 Smobs</a></li>
 1154 <li><a HREF="#Guile_nn15">26.7.2 Garbage Collection</a></li>
 1155 </ul>
 1156 </li>
 1157 <li><a HREF="#Guile_nn16">26.8 Native Guile pointers</a></li>
 1158 <li><a HREF="#Guile_nn17">26.9 Exception Handling</a></li>
 1159 <li><a HREF="#Guile_nn18">26.10 Procedure documentation</a></li>
 1160 <li><a HREF="#Guile_nn19">26.11 Procedures with setters</a></li>
 1161 <li><a HREF="#Guile_nn20">26.12 GOOPS Proxy Classes</a>
 1162 <ul>
 1163 <li><a HREF="#Guile_nn21">26.12.1 Naming Issues</a></li>
 1164 <li><a HREF="#Guile_nn22">26.12.2 Linking</a></li>
 1165 </ul>
 1166 </li>
 1167 </ul>
 1168 <b><a HREF="#Java">27 SWIG and Java</a></b>
 1169 <ul>
 1170 <li><a HREF="#Java_overview">27.1 Overview</a></li>
 1171 <li><a HREF="#Java_preliminaries">27.2 Preliminaries</a>
 1172 <ul>
 1173 <li><a HREF="#Java_running_swig">27.2.1 Running SWIG</a></li>
 1174 <li><a HREF="#Java_commandline">27.2.2 Additional Commandline Options</a>
 1175 </li>
 1176 <li><a HREF="#Java_getting_right_headers">27.2.3 Getting the right
 1177  header files</a></li>
 1178 <li><a HREF="#Java_compiling_dynamic">27.2.4 Compiling a dynamic module</a>
 1179 </li>
 1180 <li><a HREF="#Java_using_module">27.2.5 Using your module</a></li>
 1181 <li><a HREF="#Java_dynamic_linking_problems">27.2.6 Dynamic linking
 1182  problems</a></li>
 1183 <li><a HREF="#Java_compilation_problems_cpp">27.2.7 Compilation problems
 1184  and compiling with C++</a></li>
 1185 <li><a HREF="#Java_building_windows">27.2.8 Building on Windows</a>
 1186 <ul>
 1187 <li><a HREF="#Java_visual_studio"> Running SWIG from Visual
 1188  Studio</a></li>
 1189 <li><a HREF="#Java_nmake"> Using NMAKE</a></li>
 1190 </ul>
 1191 </li>
 1192 </ul>
 1193 </li>
 1194 <li><a HREF="#Java_basic_tour">27.3 A tour of basic C/C++ wrapping</a>
 1195 <ul>
 1196 <li><a HREF="#Java_module_packages_classes">27.3.1 Modules, packages and
 1197  generated Java classes</a></li>
 1198 <li><a HREF="#Java_functions">27.3.2 Functions</a></li>
 1199 <li><a HREF="#Java_global_variables">27.3.3 Global variables</a></li>
 1200 <li><a HREF="#Java_constants">27.3.4 Constants</a></li>
 1201 <li><a HREF="#Java_enumerations">27.3.5 Enumerations</a>
 1202 <ul>
 1203 <li><a HREF="#Java_anonymous_enums"> Anonymous enums</a></li>
 1204 <li><a HREF="#Java_typesafe_enums"> Typesafe enums</a></li>
 1205 <li><a HREF="#Java_proper_enums"> Proper Java enums</a></li>
 1206 <li><a HREF="#Java_typeunsafe_enums"> Type unsafe enums</a></li>
 1207 <li><a HREF="#Java_simple_enums"> Simple enums</a></li>
 1208 </ul>
 1209 </li>
 1210 <li><a HREF="#Java_pointers">27.3.6 Pointers</a></li>
 1211 <li><a HREF="#Java_structures">27.3.7 Structures</a></li>
 1212 <li><a HREF="#Java_classes">27.3.8 C++ classes</a></li>
 1213 <li><a HREF="#Java_inheritance">27.3.9 C++ inheritance</a></li>
 1214 <li><a HREF="#Java_pointers_refs_arrays">27.3.10 Pointers, references,
 1215  arrays and pass by value</a>
 1216 <ul>
 1217 <li><a HREF="#Java_null_pointers"> Null pointers</a></li>
 1218 </ul>
 1219 </li>
 1220 <li><a HREF="#Java_overloaded_functions">27.3.11 C++ overloaded
 1221  functions</a></li>
 1222 <li><a HREF="#Java_default_arguments">27.3.12 C++ default arguments</a></li>
 1223 <li><a HREF="#Java_namespaces">27.3.13 C++ namespaces</a></li>
 1224 <li><a HREF="#Java_templates">27.3.14 C++ templates</a></li>
 1225 <li><a HREF="#Java_smart_pointers">27.3.15 C++ Smart Pointers</a>
 1226 <ul>
 1227 <li><a HREF="#Java_smart_pointers_shared_ptr"> The shared_ptr
 1228  Smart Pointer</a></li>
 1229 <li><a HREF="#Java_smart_pointers_generic"> Generic Smart
 1230  Pointers</a></li>
 1231 </ul>
 1232 </li>
 1233 </ul>
 1234 </li>
 1235 <li><a HREF="#Java_further_details">27.4 Further details on the
 1236  generated Java classes</a>
 1237 <ul>
 1238 <li><a HREF="#Java_imclass">27.4.1 The intermediary JNI class</a>
 1239 <ul>
 1240 <li><a HREF="#Java_imclass_pragmas"> The intermediary JNI class
 1241  pragmas</a></li>
 1242 </ul>
 1243 </li>
 1244 <li><a HREF="#Java_module_class">27.4.2 The Java module class</a>
 1245 <ul>
 1246 <li><a HREF="#Java_module_class_pragmas"> The Java module class
 1247  pragmas</a></li>
 1248 </ul>
 1249 </li>
 1250 <li><a HREF="#Java_proxy_classes">27.4.3 Java proxy classes</a>
 1251 <ul>
 1252 <li><a HREF="#Java_memory_management"> Memory management</a></li>
 1253 <li><a HREF="#Java_inheritance_mirroring"> Inheritance</a></li>
 1254 <li><a HREF="#Java_proxy_classes_gc"> Proxy classes and garbage
 1255  collection</a></li>
 1256 <li><a HREF="#Java_pgcpp"> The premature garbage collection
 1257  prevention parameter for proxy class marshalling</a></li>
 1258 <li><a HREF="#Java_multithread_libraries"> Single threaded
 1259  applications and thread safety</a></li>
 1260 </ul>
 1261 </li>
 1262 <li><a HREF="#Java_type_wrapper_classes">27.4.4 Type wrapper classes</a></li>
 1263 <li><a HREF="#Java_enum_classes">27.4.5 Enum classes</a>
 1264 <ul>
 1265 <li><a HREF="#Java_typesafe_enums_classes"> Typesafe enum
 1266  classes</a></li>
 1267 <li><a HREF="#Java_proper_enums_classes"> Proper Java enum
 1268  classes</a></li>
 1269 <li><a HREF="#Java_typeunsafe_enums_classes"> Type unsafe enum
 1270  classes</a></li>
 1271 </ul>
 1272 </li>
 1273 <li><a HREF="#Java_interfaces">27.4.6 Interfaces</a></li>
 1274 </ul>
 1275 </li>
 1276 <li><a HREF="#Java_directors">27.5 Cross language polymorphism using
 1277  directors</a>
 1278 <ul>
 1279 <li><a HREF="#Java_enabling_directors">27.5.1 Enabling directors</a></li>
 1280 <li><a HREF="#Java_directors_classes">27.5.2 Director classes</a></li>
 1281 <li><a HREF="#Java_directors_overhead">27.5.3 Overhead and code bloat</a>
 1282 </li>
 1283 <li><a HREF="#Java_directors_example">27.5.4 Simple directors example</a>
 1284 </li>
 1285 <li><a HREF="#Java_directors_threading">27.5.5 Director threading issues</a>
 1286 </li>
 1287 <li><a HREF="#Java_directors_performance">27.5.6 Director performance
 1288  tuning</a></li>
 1289 <li><a HREF="#Java_exceptions_from_directors">27.5.7 Java exceptions
 1290  from directors</a>
 1291 <ul>
 1292 <li><a HREF="#Java_customizing_director_exceptions"> Customizing
 1293  director exceptions</a></li>
 1294 </ul>
 1295 </li>
 1296 </ul>
 1297 </li>
 1298 <li><a HREF="#Java_allprotected">27.6 Accessing protected members</a></li>
 1299 <li><a HREF="#Java_common_customization">27.7 Common customization
 1300  features</a>
 1301 <ul>
 1302 <li><a HREF="#Java_helper_functions">27.7.1 C/C++ helper functions</a></li>
 1303 <li><a HREF="#Java_class_extension">27.7.2 Class extension with %extend</a>
 1304 </li>
 1305 <li><a HREF="#Java_proxycode">27.7.3 Class extension with %proxycode</a></li>
 1306 <li><a HREF="#Java_exception_handling">27.7.4 Exception handling with
 1307  %exception and %javaexception</a></li>
 1308 <li><a HREF="#Java_method_access">27.7.5 Method access with
 1309  %javamethodmodifiers</a></li>
 1310 </ul>
 1311 </li>
 1312 <li><a HREF="#Java_tips_techniques">27.8 Tips and techniques</a>
 1313 <ul>
 1314 <li><a HREF="#Java_input_output_parameters">27.8.1 Input and output
 1315  parameters using primitive pointers and references</a></li>
 1316 <li><a HREF="#Java_simple_pointers">27.8.2 Simple pointers</a></li>
 1317 <li><a HREF="#Java_c_arrays">27.8.3 Wrapping C arrays with Java arrays</a>
 1318 </li>
 1319 <li><a HREF="#Java_unbounded_c_arrays">27.8.4 Unbounded C Arrays</a></li>
 1320 <li><a HREF="#Java_binary_char">27.8.5 Binary data vs Strings</a></li>
 1321 <li><a HREF="#Java_heap_allocations">27.8.6 Overriding new and delete to
 1322  allocate from Java heap</a></li>
 1323 </ul>
 1324 </li>
 1325 <li><a HREF="#Java_typemaps">27.9 Java typemaps</a>
 1326 <ul>
 1327 <li><a HREF="#Java_default_primitive_type_mappings">27.9.1 Default
 1328  primitive type mappings</a></li>
 1329 <li><a HREF="#Java_default_non_primitive_typemaps">27.9.2 Default
 1330  typemaps for non-primitive types</a></li>
 1331 <li><a HREF="#Java_jvm64">27.9.3 Sixty four bit JVMs</a></li>
 1332 <li><a HREF="#Java_what_is_typemap">27.9.4 What is a typemap?</a></li>
 1333 <li><a HREF="#Java_typemaps_c_to_java_types">27.9.5 Typemaps for mapping
 1334  C/C++ types to Java types</a></li>
 1335 <li><a HREF="#Java_typemap_attributes">27.9.6 Java typemap attributes</a>
 1336 </li>
 1337 <li><a HREF="#Java_special_variables">27.9.7 Java special variables</a></li>
 1338 <li><a HREF="#Java_typemaps_for_c_and_cpp">27.9.8 Typemaps for both C
 1339  and C++ compilation</a></li>
 1340 <li><a HREF="#Java_code_typemaps">27.9.9 Java code typemaps</a></li>
 1341 <li><a HREF="#Java_directors_typemaps">27.9.10 Director specific
 1342  typemaps</a></li>
 1343 </ul>
 1344 </li>
 1345 <li><a HREF="#Java_typemap_examples">27.10 Typemap Examples</a>
 1346 <ul>
 1347 <li><a HREF="#Java_simpler_enum_classes">27.10.1 Simpler Java enums for
 1348  enums without initializers</a></li>
 1349 <li><a HREF="#Java_exception_typemap">27.10.2 Handling C++ exception
 1350  specifications as Java exceptions</a></li>
 1351 <li><a HREF="#Java_nan_exception_typemap">27.10.3 NaN Exception -
 1352  exception handling for a particular type</a></li>
 1353 <li><a HREF="#Java_converting_java_string_arrays">27.10.4 Converting
 1354  Java String arrays to char **</a></li>
 1355 <li><a HREF="#Java_expanding_java_object">27.10.5 Expanding a Java
 1356  object to multiple arguments</a></li>
 1357 <li><a HREF="#Java_using_typemaps_return_arguments">27.10.6 Using
 1358  typemaps to return arguments</a></li>
 1359 <li><a HREF="#Java_adding_downcasts">27.10.7 Adding Java downcasts to
 1360  polymorphic return types</a></li>
 1361 <li><a HREF="#Java_adding_equals_method">27.10.8 Adding an equals method
 1362  to the Java classes</a></li>
 1363 <li><a HREF="#Java_void_pointers">27.10.9 Void pointers and a common
 1364  Java base class</a></li>
 1365 <li><a HREF="#Java_struct_pointer_pointer">27.10.10 Struct pointer to
 1366  pointer</a></li>
 1367 <li><a HREF="#Java_memory_management_member_variables">27.10.11 Memory
 1368  management when returning references to member variables</a></li>
 1369 <li><a HREF="#Java_memory_management_objects">27.10.12 Memory management
 1370  for objects passed to the C++ layer</a></li>
 1371 <li><a HREF="#Java_date_marshalling">27.10.13 Date marshalling using the
 1372  javain typemap and associated attributes</a></li>
 1373 </ul>
 1374 </li>
 1375 <li><a HREF="#Java_directors_faq">27.11 Living with Java Directors</a></li>
 1376 <li><a HREF="#Java_odds_ends">27.12 Odds and ends</a>
 1377 <ul>
 1378 <li><a HREF="#Java_javadoc_comments">27.12.1 JavaDoc comments</a></li>
 1379 <li><a HREF="#Java_functional_interface">27.12.2 Functional interface
 1380  without proxy classes</a></li>
 1381 <li><a HREF="#Java_using_own_jni_functions">27.12.3 Using your own JNI
 1382  functions</a></li>
 1383 <li><a HREF="#Java_performance">27.12.4 Performance concerns and hints</a>
 1384 </li>
 1385 <li><a HREF="#Java_debugging">27.12.5 Debugging</a></li>
 1386 </ul>
 1387 </li>
 1388 <li><a HREF="#Java_examples">27.13 Java Examples</a></li>
 1389 </ul>
 1390 <b><a HREF="#Javascript">28 SWIG and Javascript</a></b>
 1391 <ul>
 1392 <li><a HREF="#Javascript_overview">28.1 Overview</a></li>
 1393 <li><a HREF="#Javascript_preliminaries">28.2 Preliminaries</a>
 1394 <ul>
 1395 <li><a HREF="#Javascript_running_swig">28.2.1 Running SWIG</a></li>
 1396 <li><a HREF="#Javascript_running_tests_examples">28.2.2 Running Tests
 1397  and Examples</a></li>
 1398 <li><a HREF="#Javascript_known_issues">28.2.3 Known Issues</a></li>
 1399 </ul>
 1400 </li>
 1401 <li><a HREF="#Javascript_integration">28.3 Integration</a>
 1402 <ul>
 1403 <li><a HREF="#Javascript_node_extensions">28.3.1 Creating node.js
 1404  Extensions</a>
 1405 <ul>
 1406 <li><a HREF="#Javascript_troubleshooting"> Troubleshooting</a></li>
 1407 </ul>
 1408 </li>
 1409 <li><a HREF="#Javascript_embedded_webkit">28.3.2 Embedded Webkit</a>
 1410 <ul>
 1411 <li><a HREF="#Javascript_osx"> Mac OS X</a></li>
 1412 <li><a HREF="#Javascript_gtk"> GTK</a></li>
 1413 </ul>
 1414 </li>
 1415 <li><a HREF="#Javascript_applications_webkit">28.3.3 Creating
 1416  Applications with node-webkit</a></li>
 1417 </ul>
 1418 </li>
 1419 <li><a HREF="#Javascript_examples">28.4 Examples</a>
 1420 <ul>
 1421 <li><a HREF="#Javascript_simple_example">28.4.1 Simple</a></li>
 1422 <li><a HREF="#Javascript_class_example">28.4.2 Class</a></li>
 1423 </ul>
 1424 </li>
 1425 <li><a HREF="#Javascript_implementation">28.5 Implementation</a>
 1426 <ul>
 1427 <li><a HREF="#Javascript_source_code">28.5.1 Source Code</a></li>
 1428 <li><a HREF="#Javascript_code_templates">28.5.2 Code Templates</a></li>
 1429 <li><a HREF="#Javascript_emitter">28.5.3 Emitter</a></li>
 1430 <li><a HREF="#Javascript_emitter_states">28.5.4 Emitter states</a></li>
 1431 <li><a HREF="#Javascript_jsc_exceptions">28.5.5 Handling Exceptions in
 1432  JavascriptCore</a></li>
 1433 </ul>
 1434 </li>
 1435 </ul>
 1436 <b><a HREF="#Lua">29 SWIG and Lua</a></b>
 1437 <ul>
 1438 <li><a HREF="#Lua_nn2">29.1 Preliminaries</a></li>
 1439 <li><a HREF="#Lua_nn3">29.2 Running SWIG</a>
 1440 <ul>
 1441 <li><a HREF="#Lua_commandline">29.2.1 Additional command line options</a>
 1442 </li>
 1443 <li><a HREF="#Lua_nn4">29.2.2 Compiling and Linking and Interpreter</a></li>
 1444 <li><a HREF="#Lua_nn5">29.2.3 Compiling a dynamic module</a></li>
 1445 <li><a HREF="#Lua_nn6">29.2.4 Using your module</a></li>
 1446 </ul>
 1447 </li>
 1448 <li><a HREF="#Lua_nn7">29.3 A tour of basic C/C++ wrapping</a>
 1449 <ul>
 1450 <li><a HREF="#Lua_nn8">29.3.1 Modules</a></li>
 1451 <li><a HREF="#Lua_nn9">29.3.2 Functions</a></li>
 1452 <li><a HREF="#Lua_nn10">29.3.3 Global variables</a></li>
 1453 <li><a HREF="#Lua_nn11">29.3.4 Constants and enums</a>
 1454 <ul>
 1455 <li><a HREF="#Lua_nn13"> Constants/enums and classes/structures</a>
 1456 </li>
 1457 </ul>
 1458 </li>
 1459 <li><a HREF="#Lua_nn12">29.3.5 Pointers</a></li>
 1460 <li><a HREF="#Lua_structures">29.3.6 Structures</a></li>
 1461 <li><a HREF="#Lua_nn14">29.3.7 C++ classes</a></li>
 1462 <li><a HREF="#Lua_nn15">29.3.8 C++ inheritance</a></li>
 1463 <li><a HREF="#Lua_nn16">29.3.9 Pointers, references, values, and arrays</a>
 1464 </li>
 1465 <li><a HREF="#Lua_nn17">29.3.10 C++ overloaded functions</a></li>
 1466 <li><a HREF="#Lua_nn18">29.3.11 C++ operators</a></li>
 1467 <li><a HREF="#Lua_nn19">29.3.12 Class extension with %extend</a></li>
 1468 <li><a HREF="#Lua_nn20">29.3.13 Using %newobject to release memory</a></li>
 1469 <li><a HREF="#Lua_nn21">29.3.14 C++ templates</a></li>
 1470 <li><a HREF="#Lua_nn22">29.3.15 C++ Smart Pointers</a></li>
 1471 <li><a HREF="#Lua_nn23">29.3.16 C++ Exceptions</a></li>
 1472 <li><a HREF="#Lua_namespaces">29.3.17 Namespaces</a>
 1473 <ul>
 1474 <li><a HREF="#Lua_nn27"> Compatibility Note</a></li>
 1475 <li><a HREF="#Lua_nn29"> Names</a></li>
 1476 <li><a HREF="#Lua_nn30"> Inheritance</a></li>
 1477 </ul>
 1478 </li>
 1479 </ul>
 1480 </li>
 1481 <li><a HREF="#Lua_nn24">29.4 Typemaps</a>
 1482 <ul>
 1483 <li><a HREF="#Lua_nn25">29.4.1 What is a typemap?</a></li>
 1484 <li><a HREF="#Lua_nn26">29.4.2 Using typemaps</a></li>
 1485 <li><a HREF="#Lua_typemap_arrays">29.4.3 Typemaps and arrays</a></li>
 1486 <li><a HREF="#Lua_typemaps_ptr_ptr_functions">29.4.4 Typemaps and
 1487  pointer-pointer functions</a></li>
 1488 </ul>
 1489 </li>
 1490 <li><a HREF="#Lua_writing_typemaps">29.5 Writing typemaps</a>
 1491 <ul>
 1492 <li><a HREF="#Lua_typemaps_write">29.5.1 Typemaps you can write</a></li>
 1493 <li><a HREF="#Lua_nn31">29.5.2 SWIG's Lua-C API</a></li>
 1494 </ul>
 1495 </li>
 1496 <li><a HREF="#Lua_nn32">29.6 Customization of your Bindings</a>
 1497 <ul>
 1498 <li><a HREF="#Lua_nn33">29.6.1 Writing your own custom wrappers</a></li>
 1499 <li><a HREF="#Lua_nn34">29.6.2 Adding additional Lua code</a></li>
 1500 </ul>
 1501 </li>
 1502 <li><a HREF="#Lua_nn35">29.7 Details on the Lua binding</a>
 1503 <ul>
 1504 <li><a HREF="#Lua_nn36">29.7.1 Binding global data into the module.</a></li>
 1505 <li><a HREF="#Lua_nn37">29.7.2 Userdata and Metatables</a></li>
 1506 <li><a HREF="#Lua_nn38">29.7.3 Memory management</a></li>
 1507 </ul>
 1508 </li>
 1509 </ul>
 1510 <b><a HREF="#Octave">30 SWIG and Octave</a></b>
 1511 <ul>
 1512 <li><a HREF="#Octave_nn2">30.1 Preliminaries</a></li>
 1513 <li><a HREF="#Octave_nn3">30.2 Running SWIG</a>
 1514 <ul>
 1515 <li><a HREF="#Octave_nn4">30.2.1 Command-line options</a></li>
 1516 <li><a HREF="#Octave_nn5">30.2.2 Compiling a dynamic module</a></li>
 1517 <li><a HREF="#Octave_nn6">30.2.3 Using your module</a></li>
 1518 </ul>
 1519 </li>
 1520 <li><a HREF="#Octave_nn7">30.3 A tour of basic C/C++ wrapping</a>
 1521 <ul>
 1522 <li><a HREF="#Octave_nn8">30.3.1 Modules</a></li>
 1523 <li><a HREF="#Octave_nn9">30.3.2 Functions</a></li>
 1524 <li><a HREF="#Octave_nn10">30.3.3 Global variables</a></li>
 1525 <li><a HREF="#Octave_nn11">30.3.4 Constants and enums</a></li>
 1526 <li><a HREF="#Octave_nn12">30.3.5 Pointers</a></li>
 1527 <li><a HREF="#Octave_nn13">30.3.6 Structures and C++ classes</a></li>
 1528 <li><a HREF="#Octave_nn15">30.3.7 C++ inheritance</a></li>
 1529 <li><a HREF="#Octave_nn17">30.3.8 C++ overloaded functions</a></li>
 1530 <li><a HREF="#Octave_nn18">30.3.9 C++ operators</a></li>
 1531 <li><a HREF="#Octave_nn19">30.3.10 Class extension with %extend</a></li>
 1532 <li><a HREF="#Octave_nn20">30.3.11 C++ templates</a></li>
 1533 <li><a HREF="#Octave_nn21">30.3.12 C++ Smart Pointers</a>
 1534 <ul>
 1535 <li><a HREF="#Octave_smart_pointers_shared_ptr"> The shared_ptr
 1536  Smart Pointer</a></li>
 1537 <li><a HREF="#Octave_smart_pointers_generic"> Generic Smart
 1538  Pointers</a></li>
 1539 </ul>
 1540 </li>
 1541 <li><a HREF="#Octave_nn22">30.3.13 Directors (calling Octave from C++
 1542  code)</a></li>
 1543 <li><a HREF="#Octave_nn23">30.3.14 Threads</a></li>
 1544 <li><a HREF="#Octave_nn24">30.3.15 Memory management</a></li>
 1545 <li><a HREF="#Octave_nn25">30.3.16 STL support</a></li>
 1546 <li><a HREF="#Octave_nn26">30.3.17 Matrix typemaps</a></li>
 1547 </ul>
 1548 </li>
 1549 </ul>
 1550 <b><a HREF="#Perl5">31 SWIG and Perl5</a></b>
 1551 <ul>
 1552 <li><a HREF="#Perl5_nn2">31.1 Overview</a></li>
 1553 <li><a HREF="#Perl5_nn3">31.2 Preliminaries</a>
 1554 <ul>
 1555 <li><a HREF="#Perl5_nn4">31.2.1 Getting the right header files</a></li>
 1556 <li><a HREF="#Perl5_nn5">31.2.2 Compiling a dynamic module</a></li>
 1557 <li><a HREF="#Perl5_nn6">31.2.3 Building a dynamic module with MakeMaker</a>
 1558 </li>
 1559 <li><a HREF="#Perl5_nn7">31.2.4 Building a static version of Perl</a></li>
 1560 <li><a HREF="#Perl5_nn8">31.2.5 Using the module</a></li>
 1561 <li><a HREF="#Perl5_nn9">31.2.6 Compilation problems and compiling with
 1562  C++</a></li>
 1563 <li><a HREF="#Perl5_nn10">31.2.7 Compiling for 64-bit platforms</a></li>
 1564 </ul>
 1565 </li>
 1566 <li><a HREF="#Perl5_nn11">31.3 Building Perl Extensions under Windows</a>
 1567 <ul>
 1568 <li><a HREF="#Perl5_nn12">31.3.1 Running SWIG from Developer Studio</a></li>
 1569 <li><a HREF="#Perl5_nn13">31.3.2 Using other compilers</a></li>
 1570 </ul>
 1571 </li>
 1572 <li><a HREF="#Perl5_nn14">31.4 The low-level interface</a>
 1573 <ul>
 1574 <li><a HREF="#Perl5_nn15">31.4.1 Functions</a></li>
 1575 <li><a HREF="#Perl5_nn16">31.4.2 Global variables</a></li>
 1576 <li><a HREF="#Perl5_nn17">31.4.3 Constants</a></li>
 1577 <li><a HREF="#Perl5_nn18">31.4.4 Pointers</a></li>
 1578 <li><a HREF="#Perl5_nn19">31.4.5 Structures</a></li>
 1579 <li><a HREF="#Perl5_nn20">31.4.6 C++ classes</a></li>
 1580 <li><a HREF="#Perl5_nn21">31.4.7 C++ classes and type-checking</a></li>
 1581 <li><a HREF="#Perl5_nn22">31.4.8 C++ overloaded functions</a></li>
 1582 <li><a HREF="#Perl5_nn23">31.4.9 Operators</a></li>
 1583 <li><a HREF="#Perl5_nn24">31.4.10 Modules and packages</a></li>
 1584 </ul>
 1585 </li>
 1586 <li><a HREF="#Perl5_nn25">31.5 Input and output parameters</a></li>
 1587 <li><a HREF="#Perl5_nn26">31.6 Exception handling</a></li>
 1588 <li><a HREF="#Perl5_nn27">31.7 Remapping datatypes with typemaps</a>
 1589 <ul>
 1590 <li><a HREF="#Perl5_nn28">31.7.1 A simple typemap example</a></li>
 1591 <li><a HREF="#Perl5_nn29">31.7.2 Perl5 typemaps</a></li>
 1592 <li><a HREF="#Perl5_nn30">31.7.3 Typemap variables</a></li>
 1593 <li><a HREF="#Perl5_nn31">31.7.4 Useful functions</a></li>
 1594 </ul>
 1595 </li>
 1596 <li><a HREF="#Perl5_nn32">31.8 Typemap Examples</a>
 1597 <ul>
 1598 <li><a HREF="#Perl5_nn33">31.8.1 Converting a Perl5 array to a char **</a>
 1599 </li>
 1600 <li><a HREF="#Perl5_nn34">31.8.2 Return values</a></li>
 1601 <li><a HREF="#Perl5_nn35">31.8.3 Returning values from arguments</a></li>
 1602 <li><a HREF="#Perl5_nn36">31.8.4 Accessing array structure members</a></li>
 1603 <li><a HREF="#Perl5_nn37">31.8.5 Turning Perl references into C pointers</a>
 1604 </li>
 1605 <li><a HREF="#Perl5_nn38">31.8.6 Pointer handling</a></li>
 1606 </ul>
 1607 </li>
 1608 <li><a HREF="#Perl5_nn39">31.9 Proxy classes</a>
 1609 <ul>
 1610 <li><a HREF="#Perl5_nn40">31.9.1 Preliminaries</a></li>
 1611 <li><a HREF="#Perl5_nn41">31.9.2 Structure and class wrappers</a></li>
 1612 <li><a HREF="#Perl5_nn42">31.9.3 Object Ownership</a></li>
 1613 <li><a HREF="#Perl5_nn43">31.9.4 Nested Objects</a></li>
 1614 <li><a HREF="#Perl5_nn44">31.9.5 Proxy Functions</a></li>
 1615 <li><a HREF="#Perl5_nn45">31.9.6 Inheritance</a></li>
 1616 <li><a HREF="#Perl5_nn46">31.9.7 Modifying the proxy methods</a></li>
 1617 </ul>
 1618 </li>
 1619 <li><a HREF="#Perl5_nn47">31.10 Adding additional Perl code</a></li>
 1620 <li><a HREF="#Perl5_directors">31.11 Cross language polymorphism</a>
 1621 <ul>
 1622 <li><a HREF="#Perl5_nn48">31.11.1 Enabling directors</a></li>
 1623 <li><a HREF="#Perl5_nn49">31.11.2 Director classes</a></li>
 1624 <li><a HREF="#Perl5_nn50">31.11.3 Ownership and object destruction</a></li>
 1625 <li><a HREF="#Perl5_nn51">31.11.4 Exception unrolling</a></li>
 1626 <li><a HREF="#Perl5_nn52">31.11.5 Overhead and code bloat</a></li>
 1627 <li><a HREF="#Perl5_nn53">31.11.6 Typemaps</a></li>
 1628 </ul>
 1629 </li>
 1630 </ul>
 1631 <b><a HREF="#Php">32 SWIG and PHP</a></b>
 1632 <ul>
 1633 <li><a HREF="#Php_nn1">32.1 Generating PHP Extensions</a>
 1634 <ul>
 1635 <li><a HREF="#Php_nn1_1">32.1.1 Building a loadable extension</a></li>
 1636 <li><a HREF="#Php_nn1_3">32.1.2 Using PHP Extensions</a></li>
 1637 </ul>
 1638 </li>
 1639 <li><a HREF="#Php_nn2">32.2 Basic PHP interface</a>
 1640 <ul>
 1641 <li><a HREF="#Php_nn2_1">32.2.1 Constants</a></li>
 1642 <li><a HREF="#Php_nn2_2">32.2.2 Global Variables</a></li>
 1643 <li><a HREF="#Php_nn2_3">32.2.3 Functions</a></li>
 1644 <li><a HREF="#Php_nn2_4">32.2.4 Overloading</a></li>
 1645 <li><a HREF="#Php_nn2_5">32.2.5 Pointers and References</a></li>
 1646 <li><a HREF="#Php_nn2_6">32.2.6 Structures and C++ classes</a>
 1647 <ul>
 1648 <li><a HREF="#Php_nn2_6_1"> Using -noproxy</a></li>
 1649 <li><a HREF="#Php_nn2_6_2"> Constructors and Destructors</a></li>
 1650 <li><a HREF="#Php_nn2_6_3"> Static Member Variables</a></li>
 1651 <li><a HREF="#Php_nn2_6_4"> Static Member Functions</a></li>
 1652 <li><a HREF="#Php_nn2_6_5"> Specifying Implemented Interfaces</a>
 1653 </li>
 1654 <li><a HREF="#Php_nn2_6_6"> Dynamic Properties</a></li>
 1655 </ul>
 1656 </li>
 1657 <li><a HREF="#Php_nn2_7">32.2.7 PHP Pragmas, Startup and Shutdown code</a>
 1658 </li>
 1659 </ul>
 1660 </li>
 1661 <li><a HREF="#Php_nn3">32.3 Cross language polymorphism</a>
 1662 <ul>
 1663 <li><a HREF="#Php_nn3_1">32.3.1 Enabling directors</a></li>
 1664 <li><a HREF="#Php_nn3_2">32.3.2 Director classes</a></li>
 1665 <li><a HREF="#Php_nn3_3">32.3.3 Ownership and object destruction</a></li>
 1666 <li><a HREF="#Php_nn3_4">32.3.4 Exception unrolling</a></li>
 1667 <li><a HREF="#Php_nn3_5">32.3.5 Overhead and code bloat</a></li>
 1668 <li><a HREF="#Php_nn3_6">32.3.6 Typemaps</a></li>
 1669 <li><a HREF="#Php_nn3_7">32.3.7 Miscellaneous</a></li>
 1670 </ul>
 1671 </li>
 1672 </ul>
 1673 <b><a HREF="#Python">33 SWIG and Python</a></b>
 1674 <ul>
 1675 <li><a HREF="#Python_nn2">33.1 Overview</a></li>
 1676 <li><a HREF="#Python_nn3">33.2 Preliminaries</a>
 1677 <ul>
 1678 <li><a HREF="#Python_nn4">33.2.1 Running SWIG</a></li>
 1679 <li><a HREF="#Python_nn6">33.2.2 Using distutils</a></li>
 1680 <li><a HREF="#Python_nn7">33.2.3 Hand compiling a dynamic module</a></li>
 1681 <li><a HREF="#Python_nn8">33.2.4 Static linking</a></li>
 1682 <li><a HREF="#Python_nn9">33.2.5 Using your module</a></li>
 1683 <li><a HREF="#Python_nn10">33.2.6 Compilation of C++ extensions</a></li>
 1684 <li><a HREF="#Python_nn11">33.2.7 Compiling for 64-bit platforms</a></li>
 1685 <li><a HREF="#Python_nn12">33.2.8 Building Python extensions under
 1686  Windows</a></li>
 1687 <li><a HREF="#Python_commandline">33.2.9 Additional Python commandline
 1688  options</a></li>
 1689 </ul>
 1690 </li>
 1691 <li><a HREF="#Python_nn13">33.3 A tour of basic C/C++ wrapping</a>
 1692 <ul>
 1693 <li><a HREF="#Python_nn14">33.3.1 Modules</a></li>
 1694 <li><a HREF="#Python_nn15">33.3.2 Functions</a></li>
 1695 <li><a HREF="#Python_nn16">33.3.3 Global variables</a></li>
 1696 <li><a HREF="#Python_nn17">33.3.4 Constants and enums</a></li>
 1697 <li><a HREF="#Python_nn18">33.3.5 Pointers</a></li>
 1698 <li><a HREF="#Python_nn19">33.3.6 Structures</a></li>
 1699 <li><a HREF="#Python_nn20">33.3.7 C++ classes</a></li>
 1700 <li><a HREF="#Python_nn21">33.3.8 C++ inheritance</a></li>
 1701 <li><a HREF="#Python_nn22">33.3.9 Pointers, references, values, and
 1702  arrays</a></li>
 1703 <li><a HREF="#Python_nn23">33.3.10 C++ overloaded functions</a></li>
 1704 <li><a HREF="#Python_nn24">33.3.11 C++ operators</a></li>
 1705 <li><a HREF="#Python_nn25">33.3.12 C++ namespaces</a></li>
 1706 <li><a HREF="#Python_nn26">33.3.13 C++ templates</a></li>
 1707 <li><a HREF="#Python_nn27">33.3.14 C++ Smart Pointers</a>
 1708 <ul>
 1709 <li><a HREF="#Python_smart_pointers_shared_ptr"> The shared_ptr
 1710  Smart Pointer</a></li>
 1711 <li><a HREF="#Python_smart_pointers_generic"> Generic Smart
 1712  Pointers</a></li>
 1713 </ul>
 1714 </li>
 1715 <li><a HREF="#Python_nn27a">33.3.15 C++ reference counted objects</a></li>
 1716 </ul>
 1717 </li>
 1718 <li><a HREF="#Python_nn28">33.4 Further details on the Python class
 1719  interface</a>
 1720 <ul>
 1721 <li><a HREF="#Python_nn29">33.4.1 Proxy classes</a></li>
 1722 <li><a HREF="#Python_builtin_types">33.4.2 Built-in Types</a>
 1723 <ul>
 1724 <li><a HREF="#Python_builtin_limitations"> Limitations</a></li>
 1725 <li><a HREF="#Python_builtin_overloads"> Operator overloads and
 1726  slots -- use them!</a></li>
 1727 </ul>
 1728 </li>
 1729 <li><a HREF="#Python_nn30">33.4.3 Memory management</a></li>
 1730 </ul>
 1731 </li>
 1732 <li><a HREF="#Python_directors">33.5 Cross language polymorphism</a>
 1733 <ul>
 1734 <li><a HREF="#Python_nn33">33.5.1 Enabling directors</a></li>
 1735 <li><a HREF="#Python_nn34">33.5.2 Director classes</a></li>
 1736 <li><a HREF="#Python_nn35">33.5.3 Ownership and object destruction</a></li>
 1737 <li><a HREF="#Python_nn36">33.5.4 Exception unrolling</a></li>
 1738 <li><a HREF="#Python_nn37">33.5.5 Overhead and code bloat</a></li>
 1739 <li><a HREF="#Python_nn38">33.5.6 Typemaps</a></li>
 1740 <li><a HREF="#Python_nn39">33.5.7 Miscellaneous</a></li>
 1741 </ul>
 1742 </li>
 1743 <li><a HREF="#Python_nn40">33.6 Common customization features</a>
 1744 <ul>
 1745 <li><a HREF="#Python_nn41">33.6.1 C/C++ helper functions</a></li>
 1746 <li><a HREF="#Python_nn42">33.6.2 Adding additional Python code</a></li>
 1747 <li><a HREF="#Python_nn43">33.6.3 Class extension with %extend</a></li>
 1748 <li><a HREF="#Python_nn44">33.6.4 Exception handling with %exception</a></li>
 1749 <li><a HREF="#Python_optimization">33.6.5 Optimization options</a>
 1750 <ul>
 1751 <li><a HREF="#Python_fastproxy"> -fastproxy</a></li>
 1752 </ul>
 1753 </li>
 1754 </ul>
 1755 </li>
 1756 <li><a HREF="#Python_nn45">33.7 Tips and techniques</a>
 1757 <ul>
 1758 <li><a HREF="#Python_nn46">33.7.1 Input and output parameters</a></li>
 1759 <li><a HREF="#Python_nn47">33.7.2 Simple pointers</a></li>
 1760 <li><a HREF="#Python_nn48">33.7.3 Unbounded C Arrays</a></li>
 1761 <li><a HREF="#Python_nn49">33.7.4 String handling</a></li>
 1762 <li><a HREF="#Python_default_args">33.7.5 Default arguments</a></li>
 1763 </ul>
 1764 </li>
 1765 <li><a HREF="#Python_nn53">33.8 Typemaps</a>
 1766 <ul>
 1767 <li><a HREF="#Python_nn54">33.8.1 What is a typemap?</a></li>
 1768 <li><a HREF="#Python_nn55">33.8.2 Python typemaps</a></li>
 1769 <li><a HREF="#Python_nn56">33.8.3 Typemap variables</a></li>
 1770 <li><a HREF="#Python_nn57">33.8.4 Useful Python Functions</a></li>
 1771 </ul>
 1772 </li>
 1773 <li><a HREF="#Python_nn58">33.9 Typemap Examples</a>
 1774 <ul>
 1775 <li><a HREF="#Python_nn59">33.9.1 Converting Python list to a char **</a>
 1776 </li>
 1777 <li><a HREF="#Python_nn60">33.9.2 Expanding a Python object into
 1778  multiple arguments</a></li>
 1779 <li><a HREF="#Python_nn61">33.9.3 Using typemaps to return arguments</a></li>
 1780 <li><a HREF="#Python_nn62">33.9.4 Mapping Python tuples into small
 1781  arrays</a></li>
 1782 <li><a HREF="#Python_nn63">33.9.5 Mapping sequences to C arrays</a></li>
 1783 <li><a HREF="#Python_nn64">33.9.6 Pointer handling</a></li>
 1784 <li><a HREF="#Python_memory_management_member_variables">33.9.7 Memory
 1785  management when returning references to member variables</a></li>
 1786 </ul>
 1787 </li>
 1788 <li><a HREF="#Python_nn65">33.10 Docstring Features</a>
 1789 <ul>
 1790 <li><a HREF="#Python_nn66">33.10.1 Module docstring</a></li>
 1791 <li><a HREF="#Python_nn67">33.10.2 %feature(&quot;autodoc&quot;)</a>
 1792 <ul>
 1793 <li><a HREF="#Python_nn68"> %feature(&quot;autodoc&quot;, &quot;0&quot;)</a></li>
 1794 <li><a HREF="#Python_nn69"> %feature(&quot;autodoc&quot;, &quot;1&quot;)</a></li>
 1795 <li><a HREF="#Python_autodoc2"> %feature(&quot;autodoc&quot;, &quot;2&quot;)</a></li>
 1796 <li><a HREF="#Python_autodoc3"> %feature(&quot;autodoc&quot;, &quot;3&quot;)</a></li>
 1797 <li><a HREF="#Python_nn70"> %feature(&quot;autodoc&quot;, &quot;docstring&quot;)</a>
 1798 </li>
 1799 </ul>
 1800 </li>
 1801 <li><a HREF="#Python_nn71">33.10.3 %feature(&quot;docstring&quot;)</a></li>
 1802 <li><a HREF="#Python_doxygen_docstrings">33.10.4 Doxygen comments</a></li>
 1803 </ul>
 1804 </li>
 1805 <li><a HREF="#Python_nn72">33.11 Python Packages</a>
 1806 <ul>
 1807 <li><a HREF="#Python_modulepackage">33.11.1 Setting the Python package</a>
 1808 </li>
 1809 <li><a HREF="#Python_absrelimports">33.11.2 Absolute and relative
 1810  imports</a></li>
 1811 <li><a HREF="#Python_absimport">33.11.3 Enforcing absolute import
 1812  semantics</a></li>
 1813 <li><a HREF="#Python_importfrominit">33.11.4 Importing from __init__.py</a>
 1814 </li>
 1815 <li><a HREF="#Python_implicit_namespace_packages">33.11.5 Implicit
 1816  namespace packages</a></li>
 1817 <li><a HREF="#Python_package_search">33.11.6 Location of modules</a>
 1818 <ul>
 1819 <li><a HREF="#Python_package_search_both_package_modules"> Both
 1820  modules in the same package</a></li>
 1821 <li><a HREF="#Python_package_search_both_global_modules"> Both
 1822  modules are global</a></li>
 1823 <li><a HREF="#Python_package_search_wrapper_split"> Split
 1824  modules custom configuration</a></li>
 1825 <li><a HREF="#Python_custom_module_import"> More on customizing
 1826  the module import code</a></li>
 1827 <li><a HREF="#Python_package_search_static"> Statically linked
 1828  C modules</a></li>
 1829 </ul>
 1830 </li>
 1831 </ul>
 1832 </li>
 1833 <li><a HREF="#Python_python3support">33.12 Python 3 Support</a>
 1834 <ul>
 1835 <li><a HREF="#Python_annotations">33.12.1 Python function annotations
 1836  and variable annotations</a>
 1837 <ul>
 1838 <li><a HREF="#Python_annotations_c"> C/C++ annotation types</a></li>
 1839 </ul>
 1840 </li>
 1841 <li><a HREF="#Python_nn75">33.12.2 Buffer interface</a></li>
 1842 <li><a HREF="#Python_nn76">33.12.3 Abstract base classes</a></li>
 1843 <li><a HREF="#Python_nn77">33.12.4 Byte string output conversion</a></li>
 1844 <li><a HREF="#Python_2_unicode">33.12.5 Python 2 Unicode</a></li>
 1845 </ul>
 1846 </li>
 1847 <li><a HREF="#Python_multithreaded">33.13 Support for Multithreaded
 1848  Applications</a>
 1849 <ul>
 1850 <li><a HREF="#Python_thread_UI">33.13.1 UI for Enabling Multithreading
 1851  Support</a></li>
 1852 <li><a HREF="#Python_thread_performance">33.13.2 Multithread Performance</a>
 1853 </li>
 1854 </ul>
 1855 </li>
 1856 </ul>
 1857 <b><a HREF="#R">34 SWIG and R</a></b>
 1858 <ul>
 1859 <li><a HREF="#R_nn2">34.1 Bugs</a></li>
 1860 <li><a HREF="#R_nn3">34.2 Using R and SWIG</a></li>
 1861 <li><a HREF="#R_nn4">34.3 Precompiling large R files</a></li>
 1862 <li><a HREF="#R_nn5">34.4 General policy</a></li>
 1863 <li><a HREF="#R_language_conventions">34.5 Language conventions</a></li>
 1864 <li><a HREF="#R_nn6">34.6 C++ classes</a>
 1865 <ul>
 1866 <li><a HREF="#R_class_examples">34.6.1 Examples</a></li>
 1867 </ul>
 1868 </li>
 1869 <li><a HREF="#R_nn7">34.7 Enumerations</a></li>
 1870 </ul>
 1871 <b><a HREF="#Ruby">35 SWIG and Ruby</a></b>
 1872 <ul>
 1873 <li><a HREF="#Ruby_nn2">35.1 Preliminaries</a>
 1874 <ul>
 1875 <li><a HREF="#Ruby_nn3">35.1.1 Running SWIG</a></li>
 1876 <li><a HREF="#Ruby_nn4">35.1.2 Getting the right header files</a></li>
 1877 <li><a HREF="#Ruby_nn5">35.1.3 Compiling a dynamic module</a></li>
 1878 <li><a HREF="#Ruby_nn6">35.1.4 Using your module</a></li>
 1879 <li><a HREF="#Ruby_nn7">35.1.5 Static linking</a></li>
 1880 <li><a HREF="#Ruby_nn8">35.1.6 Compilation of C++ extensions</a></li>
 1881 </ul>
 1882 </li>
 1883 <li><a HREF="#Ruby_nn9">35.2 Building Ruby Extensions under Windows
 1884  95/NT</a>
 1885 <ul>
 1886 <li><a HREF="#Ruby_nn10">35.2.1 Running SWIG from Developer Studio</a></li>
 1887 </ul>
 1888 </li>
 1889 <li><a HREF="#Ruby_nn11">35.3 The Ruby-to-C/C++ Mapping</a>
 1890 <ul>
 1891 <li><a HREF="#Ruby_nn12">35.3.1 Modules</a></li>
 1892 <li><a HREF="#Ruby_nn13">35.3.2 Functions</a></li>
 1893 <li><a HREF="#Ruby_nn14">35.3.3 Variable Linking</a></li>
 1894 <li><a HREF="#Ruby_nn15">35.3.4 Constants</a></li>
 1895 <li><a HREF="#Ruby_nn16">35.3.5 Pointers</a></li>
 1896 <li><a HREF="#Ruby_nn17">35.3.6 Structures</a></li>
 1897 <li><a HREF="#Ruby_nn18">35.3.7 C++ classes</a></li>
 1898 <li><a HREF="#Ruby_nn19">35.3.8 C++ Inheritance</a></li>
 1899 <li><a HREF="#Ruby_nn20">35.3.9 C++ Overloaded Functions</a></li>
 1900 <li><a HREF="#Ruby_nn21">35.3.10 C++ Operators</a></li>
 1901 <li><a HREF="#Ruby_nn22">35.3.11 C++ namespaces</a></li>
 1902 <li><a HREF="#Ruby_nn23">35.3.12 C++ templates</a></li>
 1903 <li><a HREF="#Ruby_nn23_1">35.3.13 C++ Standard Template Library (STL)</a>
 1904 </li>
 1905 <li><a HREF="#Ruby_C_STL_Functors">35.3.14 C++ STL Functors</a></li>
 1906 <li><a HREF="#Ruby_C_Iterators">35.3.15 C++ STL Iterators</a></li>
 1907 <li><a HREF="#Ruby_nn24">35.3.16 C++ Smart Pointers</a>
 1908 <ul>
 1909 <li><a HREF="#Ruby_smart_pointers_shared_ptr"> The shared_ptr
 1910  Smart Pointer</a></li>
 1911 <li><a HREF="#Ruby_smart_pointers_generic"> Generic Smart
 1912  Pointers</a></li>
 1913 </ul>
 1914 </li>
 1915 <li><a HREF="#Ruby_nn25">35.3.17 Cross-Language Polymorphism</a>
 1916 <ul>
 1917 <li><a HREF="#Ruby_nn26"> Exception Unrolling</a></li>
 1918 </ul>
 1919 </li>
 1920 </ul>
 1921 </li>
 1922 <li><a HREF="#Ruby_nn27">35.4 Naming</a>
 1923 <ul>
 1924 <li><a HREF="#Ruby_nn28">35.4.1 Defining Aliases</a></li>
 1925 <li><a HREF="#Ruby_nn29">35.4.2 Predicate Methods</a></li>
 1926 <li><a HREF="#Ruby_nn30">35.4.3 Bang Methods</a></li>
 1927 <li><a HREF="#Ruby_nn31">35.4.4 Getters and Setters</a></li>
 1928 </ul>
 1929 </li>
 1930 <li><a HREF="#Ruby_nn32">35.5 Input and output parameters</a></li>
 1931 <li><a HREF="#Ruby_nn33">35.6 Exception handling</a>
 1932 <ul>
 1933 <li><a HREF="#Ruby_nn34">35.6.1 Using the %exception directive</a></li>
 1934 <li><a HREF="#Ruby_nn34_2">35.6.2 Handling Ruby Blocks</a></li>
 1935 <li><a HREF="#Ruby_nn35">35.6.3 Raising exceptions</a></li>
 1936 <li><a HREF="#Ruby_nn36">35.6.4 Exception classes</a></li>
 1937 </ul>
 1938 </li>
 1939 <li><a HREF="#Ruby_nn37">35.7 Typemaps</a>
 1940 <ul>
 1941 <li><a HREF="#Ruby_nn38">35.7.1 What is a typemap?</a></li>
 1942 <li><a HREF="#Ruby_Typemap_scope">35.7.2 Typemap scope</a></li>
 1943 <li><a HREF="#Ruby_Copying_a_typemap">35.7.3 Copying a typemap</a></li>
 1944 <li><a HREF="#Ruby_Deleting_a_typemap">35.7.4 Deleting a typemap</a></li>
 1945 <li><a HREF="#Ruby_Placement_of_typemaps">35.7.5 Placement of typemaps</a>
 1946 </li>
 1947 <li><a HREF="#Ruby_nn39">35.7.6 Ruby typemaps</a>
 1948 <ul>
 1949 <li><a HREF="#Ruby_in_typemap"> &quot;in&quot; typemap</a></li>
 1950 <li><a HREF="#Ruby_typecheck_typemap"> &quot;typecheck&quot; typemap</a></li>
 1951 <li><a HREF="#Ruby_out_typemap"> &quot;out&quot; typemap</a></li>
 1952 <li><a HREF="#Ruby_arginit_typemap"> &quot;arginit&quot; typemap</a></li>
 1953 <li><a HREF="#Ruby_default_typemap"> &quot;default&quot; typemap</a></li>
 1954 <li><a HREF="#Ruby_check_typemap"> &quot;check&quot; typemap</a></li>
 1955 <li><a HREF="#Ruby_argout_typemap_"> &quot;argout&quot; typemap</a></li>
 1956 <li><a HREF="#Ruby_freearg_typemap_"> &quot;freearg&quot; typemap</a></li>
 1957 <li><a HREF="#Ruby_newfree_typemap"> &quot;newfree&quot; typemap</a></li>
 1958 <li><a HREF="#Ruby_memberin_typemap"> &quot;memberin&quot; typemap</a></li>
 1959 <li><a HREF="#Ruby_varin_typemap"> &quot;varin&quot; typemap</a></li>
 1960 <li><a HREF="#Ruby_varout_typemap_"> &quot;varout&quot; typemap</a></li>
 1961 <li><a HREF="#Ruby_throws_typemap"> &quot;throws&quot; typemap</a></li>
 1962 <li><a HREF="#Ruby_directorin_typemap"> directorin typemap</a></li>
 1963 <li><a HREF="#Ruby_directorout_typemap"> directorout typemap</a>
 1964 </li>
 1965 <li><a HREF="#Ruby_directorargout_typemap"> directorargout
 1966  typemap</a></li>
 1967 <li><a HREF="#Ruby_ret_typemap"> ret typemap</a></li>
 1968 <li><a HREF="#Ruby_globalin_typemap"> globalin typemap</a></li>
 1969 </ul>
 1970 </li>
 1971 <li><a HREF="#Ruby_nn40">35.7.7 Typemap variables</a></li>
 1972 <li><a HREF="#Ruby_nn41">35.7.8 Useful Functions</a>
 1973 <ul>
 1974 <li><a HREF="#Ruby_nn42"> C Datatypes to Ruby Objects</a></li>
 1975 <li><a HREF="#Ruby_nn43"> Ruby Objects to C Datatypes</a></li>
 1976 <li><a HREF="#Ruby_nn44"> Macros for VALUE</a></li>
 1977 <li><a HREF="#Ruby_nn45"> Exceptions</a></li>
 1978 <li><a HREF="#Ruby_nn46"> Iterators</a></li>
 1979 </ul>
 1980 </li>
 1981 <li><a HREF="#Ruby_nn47">35.7.9 Typemap Examples</a></li>
 1982 <li><a HREF="#Ruby_nn48">35.7.10 Converting a Ruby array to a char **</a>
 1983 </li>
 1984 <li><a HREF="#Ruby_nn49">35.7.11 Collecting arguments in a hash</a></li>
 1985 <li><a HREF="#Ruby_nn50">35.7.12 Pointer handling</a>
 1986 <ul>
 1987 <li><a HREF="#Ruby_nn51"> Ruby Datatype Wrapping</a></li>
 1988 </ul>
 1989 </li>
 1990 <li><a HREF="#Ruby_nn52">35.7.13 Example: STL Vector to Ruby Array</a></li>
 1991 </ul>
 1992 </li>
 1993 <li><a HREF="#Ruby_nn65">35.8 Docstring Features</a>
 1994 <ul>
 1995 <li><a HREF="#Ruby_nn66">35.8.1 Module docstring</a></li>
 1996 <li><a HREF="#Ruby_nn67">35.8.2 %feature(&quot;autodoc&quot;)</a>
 1997 <ul>
 1998 <li><a HREF="#Ruby_nn68"> %feature(&quot;autodoc&quot;, &quot;0&quot;)</a></li>
 1999 <li><a HREF="#Ruby_autodoc1"> %feature(&quot;autodoc&quot;, &quot;1&quot;)</a></li>
 2000 <li><a HREF="#Ruby_autodoc2"> %feature(&quot;autodoc&quot;, &quot;2&quot;)</a></li>
 2001 <li><a HREF="#Ruby_feature_autodoc3"> %feature(&quot;autodoc&quot;, &quot;3&quot;)</a>
 2002 </li>
 2003 <li><a HREF="#Ruby_nn70"> %feature(&quot;autodoc&quot;, &quot;docstring&quot;)</a></li>
 2004 </ul>
 2005 </li>
 2006 <li><a HREF="#Ruby_nn71">35.8.3 %feature(&quot;docstring&quot;)</a></li>
 2007 </ul>
 2008 </li>
 2009 <li><a HREF="#Ruby_nn53">35.9 Advanced Topics</a>
 2010 <ul>
 2011 <li><a HREF="#Ruby_operator_overloading">35.9.1 Operator overloading</a></li>
 2012 <li><a HREF="#Ruby_nn55">35.9.2 Creating Multi-Module Packages</a></li>
 2013 <li><a HREF="#Ruby_nn56">35.9.3 Specifying Mixin Modules</a></li>
 2014 </ul>
 2015 </li>
 2016 <li><a HREF="#Ruby_nn57">35.10 Memory Management</a>
 2017 <ul>
 2018 <li><a HREF="#Ruby_nn58">35.10.1 Mark and Sweep Garbage Collector</a></li>
 2019 <li><a HREF="#Ruby_nn59">35.10.2 Object Ownership</a></li>
 2020 <li><a HREF="#Ruby_nn60">35.10.3 Object Tracking</a></li>
 2021 <li><a HREF="#Ruby_nn61">35.10.4 Mark Functions</a></li>
 2022 <li><a HREF="#Ruby_nn62">35.10.5 Free Functions</a></li>
 2023 <li><a HREF="#Ruby_nn63">35.10.6 Embedded Ruby and the C++ Stack</a></li>
 2024 </ul>
 2025 </li>
 2026 </ul>
 2027 <b><a HREF="#Scilab">36 SWIG and Scilab</a></b>
 2028 <ul>
 2029 <li><a HREF="#Scilab_preliminaries">36.1 Preliminaries</a></li>
 2030 <li><a HREF="#Scilab_running_swig">36.2 Running SWIG</a>
 2031 <ul>
 2032 <li><a HREF="#Scilab_running_swig_generating_module">36.2.1 Generating
 2033  the module</a></li>
 2034 <li><a HREF="#Scilab_running_swig_building_module">36.2.2 Building the
 2035  module</a></li>
 2036 <li><a HREF="#Scilab_running_swig_loading_module">36.2.3 Loading the
 2037  module</a></li>
 2038 <li><a HREF="#Scilab_running_swig_using_module">36.2.4 Using the module</a>
 2039 </li>
 2040 <li><a HREF="#Scilab_running_swig_options">36.2.5 Scilab command line
 2041  options</a></li>
 2042 </ul>
 2043 </li>
 2044 <li><a HREF="#Scilab_wrapping">36.3 A basic tour of C/C++ wrapping</a>
 2045 <ul>
 2046 <li><a HREF="#Scilab_wrapping_overview">36.3.1 Overview</a></li>
 2047 <li><a HREF="#Scilab_wrapping_identifiers">36.3.2 Identifiers</a></li>
 2048 <li><a HREF="#Scilab_wrapping_functions">36.3.3 Functions</a>
 2049 <ul>
 2050 <li><a HREF="#Scilab_nn13"> Argument passing</a></li>
 2051 <li><a HREF="#Scilab_nn14"> Multiple output arguments</a></li>
 2052 </ul>
 2053 </li>
 2054 <li><a HREF="#Scilab_wrapping_global_variables">36.3.4 Global variables</a>
 2055 </li>
 2056 <li><a HREF="#Scilab_wrapping_constants_and_enums">36.3.5 Constants and
 2057  enumerations</a>
 2058 <ul>
 2059 <li><a HREF="#Scilab_wrapping_constants"> Constants</a></li>
 2060 <li><a HREF="#Scilab_wrapping_enums"> Enumerations</a></li>
 2061 </ul>
 2062 </li>
 2063 <li><a HREF="#Scilab_wrapping_pointers">36.3.6 Pointers</a>
 2064 <ul>
 2065 <li><a HREF="#Scilab_wrapping_pointers_utility_functions">
 2066  Utility functions</a></li>
 2067 <li><a HREF="#Scilab_wrapping_pointers_null_pointers"> Null
 2068  pointers:</a></li>
 2069 </ul>
 2070 </li>
 2071 <li><a HREF="#Scilab_wrapping_structs">36.3.7 Structures</a></li>
 2072 <li><a HREF="#Scilab_wrapping_cpp_classes">36.3.8 C++ classes</a></li>
 2073 <li><a HREF="#Scilab_wrapping_cpp_inheritance">36.3.9 C++ inheritance</a>
 2074 </li>
 2075 <li><a HREF="#Scilab_wrapping_cpp_overloading">36.3.10 C++ overloading</a>
 2076 </li>
 2077 <li><a HREF="#Scilab_wrapping_pointers_references_values_arrays">36.3.11
 2078  Pointers, references, values, and arrays</a></li>
 2079 <li><a HREF="#Scilab_wrapping_cpp_templates">36.3.12 C++ templates</a></li>
 2080 <li><a HREF="#Scilab_wrapping_cpp_operators">36.3.13 C++ operators</a></li>
 2081 <li><a HREF="#Scilab_wrapping_cpp_namespaces">36.3.14 C++ namespaces</a></li>
 2082 <li><a HREF="#Scilab_wrapping_cpp_exceptions">36.3.15 C++ exceptions</a></li>
 2083 <li><a HREF="#Scilab_wrapping_cpp_stl">36.3.16 C++ STL</a></li>
 2084 </ul>
 2085 </li>
 2086 <li><a HREF="#Scilab_typemaps">36.4 Type mappings and libraries</a>
 2087 <ul>
 2088 <li><a HREF="#Scilab_typemaps_primitive_types">36.4.1 Default primitive
 2089  type mappings</a></li>
 2090 <li><a HREF="#Scilab_typemaps_arrays">36.4.2 Arrays</a></li>
 2091 <li><a HREF="#Scilab_typemaps_pointer-to-pointers">36.4.3
 2092  Pointer-to-pointers</a></li>
 2093 <li><a HREF="#Scilab_typemaps_matrices">36.4.4 Matrices</a></li>
 2094 <li><a HREF="#Scilab_typemaps_stl">36.4.5 STL</a></li>
 2095 </ul>
 2096 </li>
 2097 <li><a HREF="#Scilab_module_initialization">36.5 Module initialization</a>
 2098 </li>
 2099 <li><a HREF="#Scilab_building_modes">36.6 Building modes</a>
 2100 <ul>
 2101 <li><a HREF="#Scilab_building_modes_nobuilder_mode">36.6.1 No-builder
 2102  mode</a></li>
 2103 <li><a HREF="#Scilab_building_modes_builder_mode">36.6.2 Builder mode</a>
 2104 </li>
 2105 </ul>
 2106 </li>
 2107 <li><a HREF="#Scilab_generated_scripts">36.7 Generated scripts</a>
 2108 <ul>
 2109 <li><a HREF="#Scilab_generated_scripts_builder_script">36.7.1 Builder
 2110  script</a></li>
 2111 <li><a HREF="#Scilab_generated_scripts_loader_script">36.7.2 Loader
 2112  script</a></li>
 2113 </ul>
 2114 </li>
 2115 <li><a HREF="#Scilab_other_resources">36.8 Other resources</a></li>
 2116 </ul>
 2117 <b><a HREF="#Tcl">37 SWIG and Tcl</a></b>
 2118 <ul>
 2119 <li><a HREF="#Tcl_nn2">37.1 Preliminaries</a>
 2120 <ul>
 2121 <li><a HREF="#Tcl_nn3">37.1.1 Getting the right header files</a></li>
 2122 <li><a HREF="#Tcl_nn4">37.1.2 Compiling a dynamic module</a></li>
 2123 <li><a HREF="#Tcl_nn5">37.1.3 Static linking</a></li>
 2124 <li><a HREF="#Tcl_nn6">37.1.4 Using your module</a></li>
 2125 <li><a HREF="#Tcl_nn7">37.1.5 Compilation of C++ extensions</a></li>
 2126 <li><a HREF="#Tcl_nn8">37.1.6 Compiling for 64-bit platforms</a></li>
 2127 <li><a HREF="#Tcl_nn9">37.1.7 Setting a package prefix</a></li>
 2128 <li><a HREF="#Tcl_nn10">37.1.8 Using namespaces</a></li>
 2129 </ul>
 2130 </li>
 2131 <li><a HREF="#Tcl_nn11">37.2 Building Tcl/Tk Extensions under Windows
 2132  95/NT</a>
 2133 <ul>
 2134 <li><a HREF="#Tcl_nn12">37.2.1 Running SWIG from Developer Studio</a></li>
 2135 <li><a HREF="#Tcl_nn13">37.2.2 Using NMAKE</a></li>
 2136 </ul>
 2137 </li>
 2138 <li><a HREF="#Tcl_nn14">37.3 A tour of basic C/C++ wrapping</a>
 2139 <ul>
 2140 <li><a HREF="#Tcl_nn15">37.3.1 Modules</a></li>
 2141 <li><a HREF="#Tcl_nn16">37.3.2 Functions</a></li>
 2142 <li><a HREF="#Tcl_nn17">37.3.3 Global variables</a></li>
 2143 <li><a HREF="#Tcl_nn18">37.3.4 Constants and enums</a></li>
 2144 <li><a HREF="#Tcl_nn19">37.3.5 Pointers</a></li>
 2145 <li><a HREF="#Tcl_nn20">37.3.6 Structures</a></li>
 2146 <li><a HREF="#Tcl_nn21">37.3.7 C++ classes</a></li>
 2147 <li><a HREF="#Tcl_nn22">37.3.8 C++ inheritance</a></li>
 2148 <li><a HREF="#Tcl_nn23">37.3.9 Pointers, references, values, and arrays</a>
 2149 </li>
 2150 <li><a HREF="#Tcl_nn24">37.3.10 C++ overloaded functions</a></li>
 2151 <li><a HREF="#Tcl_nn25">37.3.11 C++ operators</a></li>
 2152 <li><a HREF="#Tcl_nn26">37.3.12 C++ namespaces</a></li>
 2153 <li><a HREF="#Tcl_nn27">37.3.13 C++ templates</a></li>
 2154 <li><a HREF="#Tcl_nn28">37.3.14 C++ Smart Pointers</a></li>
 2155 </ul>
 2156 </li>
 2157 <li><a HREF="#Tcl_nn29">37.4 Further details on the Tcl class interface</a>
 2158 <ul>
 2159 <li><a HREF="#Tcl_nn30">37.4.1 Proxy classes</a></li>
 2160 <li><a HREF="#Tcl_nn31">37.4.2 Memory management</a></li>
 2161 </ul>
 2162 </li>
 2163 <li><a HREF="#Tcl_nn32">37.5 Input and output parameters</a></li>
 2164 <li><a HREF="#Tcl_nn33">37.6 Exception handling</a></li>
 2165 <li><a HREF="#Tcl_nn34">37.7 Typemaps</a>
 2166 <ul>
 2167 <li><a HREF="#Tcl_nn35">37.7.1 What is a typemap?</a></li>
 2168 <li><a HREF="#Tcl_nn36">37.7.2 Tcl typemaps</a></li>
 2169 <li><a HREF="#Tcl_nn37">37.7.3 Typemap variables</a></li>
 2170 <li><a HREF="#Tcl_nn38">37.7.4 Converting a Tcl list to a char **</a></li>
 2171 <li><a HREF="#Tcl_nn39">37.7.5 Returning values in arguments</a></li>
 2172 <li><a HREF="#Tcl_nn40">37.7.6 Useful functions</a></li>
 2173 <li><a HREF="#Tcl_nn41">37.7.7 Standard typemaps</a></li>
 2174 <li><a HREF="#Tcl_nn42">37.7.8 Pointer handling</a></li>
 2175 </ul>
 2176 </li>
 2177 <li><a HREF="#Tcl_nn43">37.8 Turning a SWIG module into a Tcl Package.</a>
 2178 </li>
 2179 <li><a HREF="#Tcl_nn44">37.9 Building new kinds of Tcl interfaces (in
 2180  Tcl)</a>
 2181 <ul>
 2182 <li><a HREF="#Tcl_nn45">37.9.1 Proxy classes</a></li>
 2183 </ul>
 2184 </li>
 2185 <li><a HREF="#Tcl_nn46">37.10 Tcl/Tk Stubs</a></li>
 2186 </ul>
 2187 <b><a HREF="#Mzscheme">38 SWIG and MzScheme/Racket</a></b>
 2188 <ul>
 2189 <li><a HREF="#MzScheme_nn2">38.1 Creating native structures</a></li>
 2190 <li><a HREF="#MzScheme_simple">38.2 Simple example</a></li>
 2191 <li><a HREF="#MzScheme_external_docs">38.3 External documentation</a></li>
 2192 </ul>
 2193 <b><a HREF="#Ocaml">39 SWIG and OCaml</a></b>
 2194 <ul>
 2195 <li><a HREF="#Ocaml_nn2">39.1 Preliminaries</a>
 2196 <ul>
 2197 <li><a HREF="#Ocaml_nn3">39.1.1 Running SWIG</a></li>
 2198 <li><a HREF="#Ocaml_nn4">39.1.2 Compiling the code</a></li>
 2199 <li><a HREF="#Ocaml_nn5">39.1.3 The camlp4 module</a></li>
 2200 <li><a HREF="#Ocaml_nn6">39.1.4 Using your module</a></li>
 2201 <li><a HREF="#Ocaml_nn7">39.1.5 Compilation problems and compiling with
 2202  C++</a></li>
 2203 </ul>
 2204 </li>
 2205 <li><a HREF="#Ocaml_nn8">39.2 The low-level Ocaml/C interface</a>
 2206 <ul>
 2207 <li><a HREF="#Ocaml_nn9">39.2.1 The generated module</a></li>
 2208 <li><a HREF="#Ocaml_nn10">39.2.2 Enums</a>
 2209 <ul>
 2210 <li><a HREF="#Ocaml_nn11"> Enum typing in Ocaml</a></li>
 2211 </ul>
 2212 </li>
 2213 <li><a HREF="#Ocaml_nn12">39.2.3 Arrays</a>
 2214 <ul>
 2215 <li><a HREF="#Ocaml_nn13"> Simple types of bounded arrays</a></li>
 2216 <li><a HREF="#Ocaml_nn14"> Complex and unbounded arrays</a></li>
 2217 <li><a HREF="#Ocaml_nn15"> Using an object</a></li>
 2218 <li><a HREF="#Ocaml_nn16"> Example typemap for a function taking
 2219  float * and int</a></li>
 2220 </ul>
 2221 </li>
 2222 <li><a HREF="#Ocaml_nn17">39.2.4 C++ Classes</a>
 2223 <ul>
 2224 <li><a HREF="#Ocaml_nn18"> STL vector and string Example</a></li>
 2225 <li><a HREF="#Ocaml_nn19"> C++ Class Example</a></li>
 2226 <li><a HREF="#Ocaml_nn20"> Compiling the example</a></li>
 2227 <li><a HREF="#Ocaml_nn21"> Sample Session</a></li>
 2228 </ul>
 2229 </li>
 2230 <li><a HREF="#Ocaml_nn22">39.2.5 Director Classes</a>
 2231 <ul>
 2232 <li><a HREF="#Ocaml_nn23"> Director Introduction</a></li>
 2233 <li><a HREF="#Ocaml_nn24"> Overriding Methods in Ocaml</a></li>
 2234 <li><a HREF="#Ocaml_nn25"> Director Usage Example</a></li>
 2235 <li><a HREF="#Ocaml_nn26"> Creating director objects</a></li>
 2236 <li><a HREF="#Ocaml_nn27"> Typemaps for directors, directorin,
 2237  directorout, directorargout</a></li>
 2238 <li><a HREF="#Ocaml_nn28"> directorin typemap</a></li>
 2239 <li><a HREF="#Ocaml_nn29"> directorout typemap</a></li>
 2240 <li><a HREF="#Ocaml_nn30"> directorargout typemap</a></li>
 2241 </ul>
 2242 </li>
 2243 <li><a HREF="#Ocaml_nn31">39.2.6 Exceptions</a></li>
 2244 </ul>
 2245 </li>
 2246 <li><a HREF="#Ocaml_nn32">39.3 Documentation Features</a>
 2247 <ul>
 2248 <li><a HREF="#Ocaml_nn33">39.3.1 Module docstring</a></li>
 2249 </ul>
 2250 </li>
 2251 </ul>
 2252 <b><a HREF="#Extending">40 Extending SWIG to support new languages</a></b>
 2253 <ul>
 2254 <li><a HREF="#Extending_nn2">40.1 Introduction</a></li>
 2255 <li><a HREF="#Extending_nn3">40.2 Prerequisites</a></li>
 2256 <li><a HREF="#Extending_nn4">40.3 The Big Picture</a></li>
 2257 <li><a HREF="#Extending_nn5">40.4 Execution Model</a>
 2258 <ul>
 2259 <li><a HREF="#Extending_nn6">40.4.1 Preprocessing</a></li>
 2260 <li><a HREF="#Extending_nn7">40.4.2 Parsing</a></li>
 2261 <li><a HREF="#Extending_nn8">40.4.3 Parse Trees</a></li>
 2262 <li><a HREF="#Extending_nn9">40.4.4 Attribute namespaces</a></li>
 2263 <li><a HREF="#Extending_nn10">40.4.5 Symbol Tables</a></li>
 2264 <li><a HREF="#Extending_nn11">40.4.6 The %feature directive</a></li>
 2265 <li><a HREF="#Extending_nn12">40.4.7 Code Generation</a></li>
 2266 <li><a HREF="#Extending_nn13">40.4.8 SWIG and XML</a></li>
 2267 </ul>
 2268 </li>
 2269 <li><a HREF="#Extending_nn14">40.5 Primitive Data Structures</a>
 2270 <ul>
 2271 <li><a HREF="#Extending_nn15">40.5.1 Strings</a></li>
 2272 <li><a HREF="#Extending_nn16">40.5.2 Hashes</a></li>
 2273 <li><a HREF="#Extending_nn17">40.5.3 Lists</a></li>
 2274 <li><a HREF="#Extending_nn18">40.5.4 Common operations</a></li>
 2275 <li><a HREF="#Extending_nn19">40.5.5 Iterating over Lists and Hashes</a></li>
 2276 <li><a HREF="#Extending_nn20">40.5.6 I/O</a></li>
 2277 </ul>
 2278 </li>
 2279 <li><a HREF="#Extending_nn21">40.6 Navigating and manipulating parse
 2280  trees</a></li>
 2281 <li><a HREF="#Extending_nn22">40.7 Working with attributes</a></li>
 2282 <li><a HREF="#Extending_nn23">40.8 Type system</a>
 2283 <ul>
 2284 <li><a HREF="#Extending_nn24">40.8.1 String encoding of types</a></li>
 2285 <li><a HREF="#Extending_nn25">40.8.2 Type construction</a></li>
 2286 <li><a HREF="#Extending_nn26">40.8.3 Type tests</a></li>
 2287 <li><a HREF="#Extending_nn27">40.8.4 Typedef and inheritance</a></li>
 2288 <li><a HREF="#Extending_nn28">40.8.5 Lvalues</a></li>
 2289 <li><a HREF="#Extending_nn29">40.8.6 Output functions</a></li>
 2290 </ul>
 2291 </li>
 2292 <li><a HREF="#Extending_nn30">40.9 Parameters</a></li>
 2293 <li><a HREF="#Extending_nn31">40.10 Writing a Language Module</a>
 2294 <ul>
 2295 <li><a HREF="#Extending_nn32">40.10.1 Execution model</a></li>
 2296 <li><a HREF="#Extending_starting_out">40.10.2 Starting out</a></li>
 2297 <li><a HREF="#Extending_nn34">40.10.3 Command line options</a></li>
 2298 <li><a HREF="#Extending_nn35">40.10.4 Configuration and preprocessing</a>
 2299 </li>
 2300 <li><a HREF="#Extending_nn36">40.10.5 Entry point to code generation</a></li>
 2301 <li><a HREF="#Extending_nn37">40.10.6 Module I/O and wrapper skeleton</a>
 2302 </li>
 2303 <li><a HREF="#Extending_nn38">40.10.7 Low-level code generators</a></li>
 2304 <li><a HREF="#Extending_configuration_files">40.10.8 Configuration files</a>
 2305 </li>
 2306 <li><a HREF="#Extending_nn40">40.10.9 Runtime support</a></li>
 2307 <li><a HREF="#Extending_nn41">40.10.10 Standard library files</a></li>
 2308 <li><a HREF="#Extending_nn42">40.10.11 User examples</a></li>
 2309 <li><a HREF="#Extending_test_suite">40.10.12 Test driven development and
 2310  the test-suite</a>
 2311 <ul>
 2312 <li><a HREF="#Extending_running_test_suite"> Running the
 2313  test-suite</a></li>
 2314 </ul>
 2315 </li>
 2316 <li><a HREF="#Extending_nn43">40.10.13 Documentation</a></li>
 2317 <li><a HREF="#Extending_coding_style_guidelines">40.10.14 Coding style
 2318  guidelines</a></li>
 2319 <li><a HREF="#Extending_language_status">40.10.15 Target language status</a>
 2320 <ul>
 2321 <li><a HREF="#Extending_supported_status"> Supported status</a>
 2322 </li>
 2323 <li><a HREF="#Extending_experimental_status"> Experimental
 2324  status</a></li>
 2325 </ul>
 2326 </li>
 2327 <li><a HREF="#Extending_prerequisites">40.10.16 Prerequisites for adding
 2328  a new language module to the SWIG distribution</a></li>
 2329 </ul>
 2330 </li>
 2331 <li><a HREF="#Extending_debugging_options">40.11 Debugging Options</a></li>
 2332 <li><a HREF="#Extending_nn46">40.12 Guide to parse tree nodes</a></li>
 2333 <li><a HREF="#Extending_further_info">40.13 Further Development
 2334  Information</a></li>
 2335 </ul>
 2336 <HR NOSHADE>
 2337 <h1><a name="Sections">SWIG-4.1 Documentation</a></h1>
 2338 <p> Last update : SWIG-4.1.1 (30 Nov 2022)</p>
 2339 <h2><a name="Sections_Sections">Sections</a></h2>
 2340 <h3><a name="Sections_core_docs">SWIG Core Documentation</a></h3>
 2341 <ul>
 2342 <li><a href="#Preface">Preface</a></li>
 2343 <li><a href="#Introduction">Introduction</a></li>
 2344 <li><a href="#Windows">Getting started on Windows</a></li>
 2345 <li><a href="#Scripting">Scripting</a></li>
 2346 <li><a href="#SWIG">SWIG Basics</a> (Read this!)</li>
 2347 <li><a href="#SWIGPlus">SWIG and C++</a></li>
 2348 <li><a href="#CPlusPlus11">SWIG and C++11</a></li>
 2349 <li><a href="#CPlusPlus14">SWIG and C++14</a></li>
 2350 <li><a href="#CPlusPlus17">SWIG and C++17</a></li>
 2351 <li><a href="#CPlusPlus20">SWIG and C++20</a></li>
 2352 <li><a href="#Preprocessor">The SWIG preprocessor</a></li>
 2353 <li><a href="#Library">The SWIG library</a></li>
 2354 <li><a href="#Arguments">Argument handling</a></li>
 2355 <li><a href="#Typemaps">Typemaps</a></li>
 2356 <li><a href="#Customization">Customization features</a></li>
 2357 <li><a href="#Contract">Contracts</a></li>
 2358 <li><a href="#Varargs">Variable length arguments</a></li>
 2359 <li><a href="#Doxygen">Doxygen documentation comments</a></li>
 2360 <li><a href="#Warnings">Warning messages</a></li>
 2361 <li><a href="#Modules">Working with Modules</a></li>
 2362 <li><a href="#CCache">Using SWIG with ccache</a></li>
 2363 </ul>
 2364 <h3><a name="Sections_language_modules">Supported Language Modules
 2365  Documentation</a></h3>
 2366 <ul>
 2367 <li><a href="#Android">Android support</a></li>
 2368 <li><a href="#CSharp">C# support</a></li>
 2369 <li><a href="#D">D support</a></li>
 2370 <li><a href="#Go">Go support</a></li>
 2371 <li><a href="#Guile">Guile support</a></li>
 2372 <li><a href="#Java">Java support</a></li>
 2373 <li><a href="#Javascript">Javascript support</a></li>
 2374 <li><a href="#Lua">Lua support</a></li>
 2375 <li><a href="#Octave">Octave support</a></li>
 2376 <li><a href="#Perl5">Perl5 support</a></li>
 2377 <li><a href="#Php">PHP support</a></li>
 2378 <li><a href="#Python">Python support</a></li>
 2379 <li><a href="#R">R support</a></li>
 2380 <li><a href="#Ruby">Ruby support</a></li>
 2381 <li><a href="#Scilab">Scilab support</a></li>
 2382 <li><a href="#Tcl">Tcl support</a></li>
 2383 </ul>
 2384 <h3><a name="Sections_experimental_language_modules">Experimental
 2385  Language Modules Documentation</a></h3>
 2386 <ul>
 2387 <li><a href="#Mzscheme">MzScheme/Racket support</a></li>
 2388 <li><a href="#Ocaml">OCaml support</a></li>
 2389 </ul>
 2390 <h3><a name="Sections_developers_docs">Developer Documentation</a></h3>
 2391 <ul>
 2392 <li><a href="#Extending">Extending SWIG</a></li>
 2393 </ul>
 2394 <HR NOSHADE>
 2395 <h1><a name="Preface">1 Preface</a></h1>
 2397 <!-- INDEX -->
 2398 <div class="sectiontoc">
 2399 <ul>
 2400 <li><a href="#Preface_nn2">Introduction</a></li>
 2401 <li><a href="#Preface_nn4">SWIG Versions</a></li>
 2402 <li><a href="#Preface_license">SWIG License</a></li>
 2403 <li><a href="#Preface_nn5">SWIG resources</a></li>
 2404 <li><a href="#Preface_nn6">Prerequisites</a></li>
 2405 <li><a href="#Preface_nn7">Organization of this manual</a></li>
 2406 <li><a href="#Preface_nn8">How to avoid reading the manual</a></li>
 2407 <li><a href="#Preface_nn9">Backwards compatibility</a></li>
 2408 <li><a href="#Preface_release_notes">Release notes</a></li>
 2409 <li><a href="#Preface_nn10">Credits</a></li>
 2410 <li><a href="#Preface_nn11">Bug reports</a></li>
 2411 <li><a href="#Preface_installation">Installation</a>
 2412 <ul>
 2413 <li><a href="#Preface_windows_installation">Windows installation</a></li>
 2414 <li><a href="#Preface_unix_installation">Unix installation</a></li>
 2415 <li><a href="#Preface_osx_installation">Macintosh OS X installation</a></li>
 2416 <li><a href="#Preface_testing">Testing</a></li>
 2417 <li><a href="#Preface_examples">Examples</a></li>
 2418 </ul>
 2419 </li>
 2420 </ul>
 2421 </div>
 2422 <!-- INDEX -->
 2423 <h2><a name="Preface_nn2">1.1 Introduction</a></h2>
 2424 <p> SWIG (Simplified Wrapper and Interface Generator) is a software
 2425  development tool for building scripting language interfaces to C and
 2426  C++ programs. Originally developed in 1995, SWIG was first used by
 2427  scientists in the Theoretical Physics Division at Los Alamos National
 2428  Laboratory for building user interfaces to simulation codes running on
 2429  the Connection Machine 5 supercomputer. In this environment, scientists
 2430  needed to work with huge amounts of simulation data, complex hardware,
 2431  and a constantly changing code base. The use of a scripting language
 2432  interface provided a simple yet highly flexible foundation for solving
 2433  these types of problems. SWIG simplifies development by largely
 2434  automating the task of scripting language integration--allowing
 2435  developers and users to focus on more important problems.</p>
 2436 <p> Although SWIG was originally developed for scientific applications,
 2437  it has since evolved into a general purpose tool that is used in a wide
 2438  variety of applications--in fact almost anything where C/C++
 2439  programming is involved.</p>
 2440 <h2><a name="Preface_nn4">1.2 SWIG Versions</a></h2>
 2441 <p> In the late 1990's, the most stable version of SWIG was release
 2442  1.1p5. Versions 1.3.x were officially development versions and these
 2443  were released over a period of 10 years starting from the year 2000.
 2444  The final version in the 1.3.x series was 1.3.40, but in truth the
 2445  1.3.x series had been stable for many years. An official stable version
 2446  was released along with the decision to make SWIG license changes and
 2447  this gave rise to version 2.0.0 in 2010. Version 3.0.0 was released in
 2448  2014 focusing on adding C++11 support and C++ nested classes. Version
 2449  4.0.0 was released in 2019 to add in Doxygen support. Some target
 2450  languages were disabled as part of a clean up and others were given a
 2451  new status of either 'Supported' or 'Experimental'.</p>
 2452 <h2><a name="Preface_license">1.3 SWIG License</a></h2>
 2453 <p> The LICENSE file shipped with SWIG in the top level directory
 2454  contains the SWIG license. For further insight into the license
 2455  including the license of SWIG's output code, please visit the SWIG
 2456  legal page - <a href="https://www.swig.org/legal.html">
 2457 https://www.swig.org/legal.html</a>.</p>
 2458 <p> The license was clarified in version 2.0.0 so that the code that
 2459  SWIG generated could be distributed under license terms of the user's
 2460  choice/requirements and at the same time the SWIG source was placed
 2461  under the GNU General Public License version 3.</p>
 2462 <h2><a name="Preface_nn5">1.4 SWIG resources</a></h2>
 2463 <p> The official location of SWIG related material is</p>
 2464 <div class="shell">
 2465 <pre>
 2466 <a href="https://www.swig.org">https://www.swig.org</a>
 2467 </pre>
 2468 </div>
 2469 <p> This site contains the latest version of the software, users guide,
 2470  and information regarding bugs, installation problems, and
 2471  implementation tricks.</p>
 2472 <p> You can also subscribe to the swig-user mailing list by visiting the
 2473  page</p>
 2474 <div class="shell">
 2475 <pre>
 2476 <a href="https://www.swig.org/mail.html">https://www.swig.org/mail.html</a>
 2477 </pre>
 2478 </div>
 2479 <p> The mailing list often discusses some of the more technical aspects
 2480  of SWIG along with information about beta releases and future work.</p>
 2481 <p> Git and Subversion access to the latest version of SWIG is also
 2482  available. More information about this can be obtained at:</p>
 2483 <div class="shell">
 2484 <pre>
 2485 <a href="https://www.swig.org/svn.html">SWIG Bleeding Edge</a>
 2486 </pre>
 2487 </div>
 2488 <h2><a name="Preface_nn6">1.5 Prerequisites</a></h2>
 2489 <p> This manual assumes that you know how to write C/C++ programs and
 2490  that you have at least heard of scripting languages such as Tcl,
 2491  Python, and Perl. A detailed knowledge of these scripting languages is
 2492  not required although some familiarity won't hurt. No prior experience
 2493  with building C extensions to these languages is required---after all,
 2494  this is what SWIG does automatically. However, you should be reasonably
 2495  familiar with the use of compilers, linkers, and makefiles since making
 2496  scripting language extensions is somewhat more complicated than writing
 2497  a normal C program.</p>
 2498 <p> Over time SWIG releases have become significantly more capable in
 2499  their C++ handling--especially support for advanced features like
 2500  namespaces, overloaded operators, and templates. Whenever possible,
 2501  this manual tries to cover the technicalities of this interface.
 2502  However, this isn't meant to be a tutorial on C++ programming. For many
 2503  of the gory details, you will almost certainly want to consult a good
 2504  C++ reference. If you don't program in C++, you may just want to skip
 2505  those parts of the manual.</p>
 2506 <h2><a name="Preface_nn7">1.6 Organization of this manual</a></h2>
 2507 <p> The first few chapters of this manual describe SWIG in general and
 2508  provide an overview of its capabilities. The remaining chapters are
 2509  devoted to specific SWIG language modules and are self contained. Thus,
 2510  if you are using SWIG to build Python interfaces, you can probably skip
 2511  to that chapter and find almost everything you need to know.</p>
 2512 <h2><a name="Preface_nn8">1.7 How to avoid reading the manual</a></h2>
 2513 <p> If you hate reading manuals, glance at the &quot;Introduction&quot; which
 2514  contains a few simple examples. These examples contain about 95% of
 2515  everything you need to know to use SWIG. After that, simply use the
 2516  language-specific chapters as a reference. The SWIG distribution also
 2517  comes with a large directory of examples that illustrate different
 2518  topics.</p>
 2519 <h2><a name="Preface_nn9">1.8 Backwards compatibility</a></h2>
 2520 <p> If you are a previous user of SWIG, don't expect SWIG to provide
 2521  complete backwards compatibility. Although the developers strive to the
 2522  utmost to keep backwards compatibility, this isn't always possible as
 2523  the primary goal over time is to make SWIG better---a process that
 2524  would simply be impossible if the developers are constantly bogged down
 2525  with backwards compatibility issues. Potential incompatibilities are
 2526  clearly marked in the detailed <a href="#Preface_release_notes">release
 2527  notes</a>.</p>
 2528 <p> If you need to work with different versions of SWIG and backwards
 2529  compatibility is an issue, you can use the SWIG_VERSION preprocessor
 2530  symbol which holds the version of SWIG being executed. SWIG_VERSION is
 2531  a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11).
 2532  This can be used in an interface file to define different typemaps,
 2533  take advantage of different features etc:</p>
 2534 <div class="code">
 2535 <pre>
 2536 #if SWIG_VERSION &gt;= 0x010311
 2537 /* Use some fancy new feature */
 2538 #endif
 2539 </pre>
 2540 </div>
 2541 <p> Note: The version symbol is not defined in the generated SWIG
 2542  wrapper file. The SWIG preprocessor has defined SWIG_VERSION since
 2543  SWIG-1.3.11.</p>
 2544 <h2><a name="Preface_release_notes">1.9 Release notes</a></h2>
 2545 <p> The CHANGES.current, CHANGES and RELEASENOTES files shipped with
 2546  SWIG in the top level directory contain, respectively, detailed release
 2547  notes for the current version, detailed release notes for previous
 2548  releases and summary release notes from SWIG-1.3.22 onwards.</p>
 2549 <h2><a name="Preface_nn10">1.10 Credits</a></h2>
 2550 <p> SWIG is an unfunded project that would not be possible without the
 2551  contributions of many people working in their spare time. If you have
 2552  benefitted from using SWIG, please consider <a href="https://www.swig.org/donate.html">
 2553 Donating to SWIG</a> to keep development going. There have been a large
 2554  varied number of people who have made contributions at all levels over
 2555  time. Contributors are mentioned either in the COPYRIGHT file or
 2556  CHANGES files shipped with SWIG or in submitted bugs.</p>
 2557 <h2><a name="Preface_nn11">1.11 Bug reports</a></h2>
 2558 <p> Although every attempt has been made to make SWIG bug-free, we are
 2559  also trying to make feature improvements that may introduce bugs. To
 2560  report a bug, either send mail to the SWIG developer list at the <a href="https://www.swig.org/mail.html">
 2561 swig-devel mailing list</a> or report a bug at the <a href="https://www.swig.org/bugs.html">
 2562 SWIG bug tracker</a>. In your report, be as specific as possible,
 2563  including (if applicable), error messages, tracebacks (if a core dump
 2564  occurred), corresponding portions of the SWIG interface file used, and
 2565  any important pieces of the SWIG generated wrapper code. We can only
 2566  fix bugs if we know about them.</p>
 2567 <h2><a name="Preface_installation">1.12 Installation</a></h2>
 2568 <h3><a name="Preface_windows_installation">1.12.1 Windows installation</a>
 2569 </h3>
 2570 <p> Please see the dedicated <a href="#Windows">Windows chapter</a> for
 2571  instructions on installing SWIG on Windows and running the examples.
 2572  The Windows distribution is called swigwin and includes a prebuilt SWIG
 2573  executable, swig.exe, included in the top level directory. Otherwise it
 2574  is exactly the same as the main SWIG distribution. There is no need to
 2575  download anything else.</p>
 2576 <h3><a name="Preface_unix_installation">1.12.2 Unix installation</a></h3>
 2577 <p> These installation instructions are for using the distributed
 2578  tarball, for example, <tt>swig-3.0.8.tar.gz</tt>. If you wish to build
 2579  and install from source on Github, extra steps are required. Please see
 2580  the <a href="https://swig.org/svn.html">Bleeding Edge</a> page on the
 2581  SWIG website.</p>
 2582 <p> You must use <a href="https://www.gnu.org/software/make/">GNU make</a>
 2583  to build and install SWIG.</p>
 2584 <p> <a href="https://www.pcre.org/">PCRE2</a> needs to be installed on
 2585  your system to build SWIG, in particular pcre2-config must be
 2586  available. If you have PCRE2 headers and libraries but not pcre2-config
 2587  itself or, alternatively, wish to override the compiler or linker flags
 2588  returned by pcre2-config, you may set PCRE2_LIBS and PCRE2_CFLAGS
 2589  variables to be used instead. And if you don't have PCRE2 at all, the
 2590  configure script will provide instructions for obtaining it.</p>
 2591 <p> To build and install SWIG, simply type the following:</p>
 2592 <div class="shell">
 2593 <pre>
 2594 $ ./configure
 2595 $ make
 2596 $ make install
 2597 </pre>
 2598 </div>
 2599 <p> By default SWIG installs itself in /usr/local. If you need to
 2600  install SWIG in a different location or in your home directory, use the
 2601  <tt>--prefix</tt> option to <tt>./configure</tt>. For example:</p>
 2602 <div class="shell">
 2603 <pre>
 2604 $ ./configure --prefix=/home/yourname/projects
 2605 $ make
 2606 $ make install
 2607 </pre>
 2608 </div>
 2609 <p> Note: the directory given to <tt>--prefix</tt> must be an absolute
 2610  pathname. Do<b> not</b> use the ~ shell-escape to refer to your home
 2611  directory. SWIG won't work properly if you do this.</p>
 2612 <p> The INSTALL file shipped in the top level directory details more
 2613  about using configure. Also try</p>
 2614 <div class="shell">
 2615 <pre>
 2616 $ ./configure --help.
 2617 </pre>
 2618 </div>
 2619 <p> The configure script will attempt to locate various packages on your
 2620  machine including Tcl, Perl5, Python and all the other target languages
 2621  that SWIG supports. Don't panic if you get 'not found' messages -- SWIG
 2622  does not need these packages to compile or run. The configure script is
 2623  actually looking for these packages so that you can try out the SWIG
 2624  examples contained in the 'Examples' directory without having to hack
 2625  Makefiles. Note that the <tt>--without-xxx</tt> options, where xxx is a
 2626  target language, have minimal effect. All they do is reduce the amount
 2627  of testing done with 'make check'. The SWIG executable and library
 2628  files installed cannot currently be configured with a subset of target
 2629  languages.</p>
 2630 <p> SWIG used to include a set of runtime libraries for some languages
 2631  for working with multiple modules. These are no longer built during the
 2632  installation stage. However, users can build them just like any wrapper
 2633  module as described in the <a href="#Modules">Modules chapter</a>. The
 2634  CHANGES file shipped with SWIG in the top level directory also lists
 2635  some examples which build the runtime library.</p>
 2636 <p> Note:</p>
 2637 <ul>
 2638 <li> If you checked the code out via Git, you will have to run <tt>
 2639 ./autogen.sh</tt> before <tt>./configure</tt>. In addition, a full build
 2640  of SWIG requires a number of packages to be installed. Full
 2641  instructions at <a href="https://www.swig.org/svn.html">SWIG bleeding
 2642  edge</a>.</li>
 2643 </ul>
 2644 <h3><a name="Preface_osx_installation">1.12.3 Macintosh OS X
 2645  installation</a></h3>
 2646 <p> SWIG is known to work on various flavors of OS X. Follow the Unix
 2647  installation instructions above. However, as of this writing, there is
 2648  still great deal of inconsistency with how shared libraries are handled
 2649  by various scripting languages on OS X.</p>
 2650 <p> Users of OS X should be aware that Darwin handles shared libraries
 2651  and linking in a radically different way than most Unix systems. In
 2652  order to test SWIG and run the examples, SWIG configures itself to use
 2653  flat namespaces and to allow undefined symbols (<tt>-flat_namespace
 2654  -undefined suppress</tt>). This mostly closely follows the Unix model
 2655  and makes it more likely that the SWIG examples will work with whatever
 2656  installation of software you might have. However, this is generally not
 2657  the recommended technique for building larger extension modules.
 2658  Instead, you should utilize Darwin's two-level namespaces. Some details
 2659  about this can be found here <a href="https://developer.apple.com/library/mac/documentation/Porting/Conceptual/PortingUnix/compiling/compiling.html#//apple_ref/doc/uid/TP40002850-BCIHJBBF">
 2660 Understanding Two-Level Namespaces</a>.</p>
 2661 <p> Needless to say, you might have to experiment a bit to get things
 2662  working at first.</p>
 2663 <h3><a name="Preface_testing">1.12.4 Testing</a></h3>
 2664 <p> If you want to test SWIG after building it, a check can be performed
 2665  on Unix operating systems. Type the following:</p>
 2666 <div class="shell">
 2667 <pre>
 2668     $ make -k check
 2669 </pre>
 2670 </div>
 2671 <p> This step can be performed either before or after installation. The
 2672  check requires at least one of the target languages to be installed. If
 2673  it fails, it may mean that you have an uninstalled language module or
 2674  that the file 'Examples/Makefile' has been incorrectly configured. It
 2675  may also fail due to compiler issues such as a broken C++ compiler.
 2676  Even if the check fails, there is a pretty good chance SWIG still works
 2677  correctly --- you will just have to mess around with one of the
 2678  examples and some makefiles to get it to work. Some tests may also fail
 2679  due to missing dependency packages, eg PCRE or Boost, but this will
 2680  require careful analysis of the configure output done during
 2681  configuration.</p>
 2682 <p> The test suite executed by the check is designed to stress-test many
 2683  parts of the implementation including obscure corner cases. If some of
 2684  these tests fail or generate warning messages, there is no reason for
 2685  alarm --- the test may be related to some new SWIG feature or a
 2686  difficult bug that we're trying to resolve. Chances are that SWIG will
 2687  work just fine for you. Note that if you have more than one CPU/core,
 2688  then you can use parallel make to speed up the check as it does take
 2689  quite some time to run, for example:</p>
 2690 <div class="shell">
 2691 <pre>
 2692     $ make -j2 -k check
 2693 </pre>
 2694 </div>
 2695 <p> Also, SWIG's support for C++ is sufficiently advanced that certain
 2696  tests may fail on older C++ compilers (for instance if your compiler
 2697  does not support member templates). These errors are harmless if you
 2698  don't intend to use these features in your own programs.</p>
 2699 <p> Note: The test-suite currently contains over 600 tests. If you have
 2700  many different target languages installed and a slow machine, it might
 2701  take more than an hour to run the test-suite.</p>
 2702 <h3><a name="Preface_examples">1.12.5 Examples</a></h3>
 2703 <p> The Examples directory contains a variety of examples of using SWIG
 2704  and it has some browsable documentation. Simply point your browser to
 2705  the file &quot;Example/index.html&quot;.</p>
 2706 <p> The Examples directory also includes Visual C++ project 6 (.dsp)
 2707  files for building some of the examples on Windows. Later versions of
 2708  Visual Studio will convert these old style project files into a current
 2709  solution file.</p>
 2710 <HR NOSHADE>
 2711 <h1><a name="Introduction">2 Introduction</a></h1>
 2713 <!-- INDEX -->
 2714 <div class="sectiontoc">
 2715 <ul>
 2716 <li><a href="#Introduction_nn2">What is SWIG?</a></li>
 2717 <li><a href="#Introduction_nn3">Why use SWIG?</a></li>
 2718 <li><a href="#Introduction_target_languages">Target languages</a>
 2719 <ul>
 2720 <li><a href="#Introduction_supported_status">Supported status</a></li>
 2721 <li><a href="#Introduction_experimental_status">Experimental status</a></li>
 2722 </ul>
 2723 </li>
 2724 <li><a href="#Introduction_nn4">A SWIG example</a>
 2725 <ul>
 2726 <li><a href="#Introduction_nn5">SWIG interface file</a></li>
 2727 <li><a href="#Introduction_nn6">The swig command</a></li>
 2728 <li><a href="#Introduction_nn7">Building a Perl5 module</a></li>
 2729 <li><a href="#Introduction_nn8">Building a Python module</a></li>
 2730 <li><a href="#Introduction_nn9">Shortcuts</a></li>
 2731 </ul>
 2732 </li>
 2733 <li><a href="#Introduction_nn10">Supported C/C++ language features</a></li>
 2734 <li><a href="#Introduction_nn11">Non-intrusive interface building</a></li>
 2735 <li><a href="#Introduction_build_system">Incorporating SWIG into a build
 2736  system</a></li>
 2737 <li><a href="#Introduction_nn12">Hands off code generation</a></li>
 2738 <li><a href="#Introduction_nn13">SWIG and freedom</a></li>
 2739 </ul>
 2740 </div>
 2741 <!-- INDEX -->
 2742 <h2><a name="Introduction_nn2">2.1 What is SWIG?</a></h2>
 2743 <p> SWIG is a software development tool that simplifies the task of
 2744  interfacing different languages to C and C++ programs. In a nutshell,
 2745  SWIG is a compiler that takes C/C++ declarations and creates the
 2746  wrappers needed to access those declarations from other languages
 2747  including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
 2748  requires no modifications to existing code and can often be used to
 2749  build a usable interface in only a few minutes. Possible applications
 2750  of SWIG include:</p>
 2751 <ul>
 2752 <li>Building interpreted interfaces to existing C programs.</li>
 2753 <li>Rapid prototyping and application development.</li>
 2754 <li>Interactive debugging.</li>
 2755 <li>Reengineering or refactoring of legacy software into scripting
 2756  language components.</li>
 2757 <li>Making a graphical user interface (using Tk for example).</li>
 2758 <li>Testing of C libraries and programs (using scripts).</li>
 2759 <li>Building high performance C modules for scripting languages.</li>
 2760 <li>Making C programming more enjoyable (or tolerable depending on your
 2761  point of view).</li>
 2762 <li>Impressing your friends.</li>
 2763 <li>Obtaining vast sums of research funding (although obviously not
 2764  applicable to the author).</li>
 2765 </ul>
 2766 <p> SWIG was originally designed to make it extremely easy for
 2767  scientists and engineers to build extensible scientific software
 2768  without having to get a degree in software engineering. Because of
 2769  this, the use of SWIG tends to be somewhat informal and ad-hoc (e.g.,
 2770  SWIG does not require users to provide formal interface specifications
 2771  as you would find in a dedicated IDL compiler). Although this style of
 2772  development isn't appropriate for every project, it is particularly
 2773  well suited to software development in the small; especially the
 2774  research and development work that is commonly found in scientific and
 2775  engineering projects. However, nowadays SWIG is known to be used in
 2776  many large open source and commercial projects.</p>
 2777 <h2><a name="Introduction_nn3">2.2 Why use SWIG?</a></h2>
 2778 <p> As stated in the previous section, the primary purpose of SWIG is to
 2779  simplify the task of integrating C/C++ with other programming
 2780  languages. However, why would anyone want to do that? To answer that
 2781  question, it is useful to list a few strengths of C/C++ programming:</p>
 2782 <ul>
 2783 <li>Excellent support for writing programming libraries.</li>
 2784 <li>High performance (number crunching, data processing, graphics,
 2785  etc.).</li>
 2786 <li>Systems programming and systems integration.</li>
 2787 <li>Large user community and software base.</li>
 2788 </ul>
 2789 <p> Next, let's list a few problems with C/C++ programming</p>
 2790 <ul>
 2791 <li>Writing a user interface is rather painful (i.e., consider
 2792  programming with MFC, X11, GTK, or any number of other libraries).</li>
 2793 <li>Testing is time consuming (the compile/debug cycle).</li>
 2794 <li>Not easy to reconfigure or customize without recompilation.</li>
 2795 <li>Modularization can be tricky.</li>
 2796 <li>Security concerns (buffer overflows for instance).</li>
 2797 </ul>
 2798 <p> To address these limitations, many programmers have arrived at the
 2799  conclusion that it is much easier to use different programming
 2800  languages for different tasks. For instance, writing a graphical user
 2801  interface may be significantly easier in a scripting language like
 2802  Python or Tcl (consider the reasons why millions of programmers have
 2803  used languages like Visual Basic if you need more proof). An
 2804  interactive interpreter might also serve as a useful debugging and
 2805  testing tool. Other languages like Java might greatly simplify the task
 2806  of writing distributed computing software. The key point is that
 2807  different programming languages offer different strengths and
 2808  weaknesses. Moreover, it is extremely unlikely that any programming is
 2809  ever going to be perfect. Therefore, by combining languages together,
 2810  you can utilize the best features of each language and greatly simplify
 2811  certain aspects of software development.</p>
 2812 <p> From the standpoint of C/C++, a lot of people use SWIG because they
 2813  want to break out of the traditional monolithic C programming model
 2814  which usually results in programs that resemble this:</p>
 2815 <ul>
 2816 <li>A collection of functions and variables that do something useful.</li>
 2817 <li>A <tt>main()</tt> program that starts everything.</li>
 2818 <li>A horrible collection of hacks that form some kind of user interface
 2819  (but which no-one really wants to touch).</li>
 2820 </ul>
 2821 <p> Instead of going down that route, incorporating C/C++ into a higher
 2822  level language often results in a more modular design, less code,
 2823  better flexibility, and increased programmer productivity.</p>
 2824 <p> SWIG tries to make the problem of C/C++ integration as painless as
 2825  possible. This allows you to focus on the underlying C program and
 2826  using the high-level language interface, but not the tedious and
 2827  complex chore of making the two languages talk to each other. At the
 2828  same time, SWIG recognizes that all applications are different.
 2829  Therefore, it provides a wide variety of customization features that
 2830  let you change almost every aspect of the language bindings. This is
 2831  the main reason why SWIG has such a large user manual ;-).</p>
 2832 <h2><a name="Introduction_target_languages">2.3 Target languages</a></h2>
 2833 <p> SWIG in essence is a tool to generate code for making C/C++ code
 2834  available to various other programming languages. These higher level
 2835  programming languages are the target languages for the SWIG code
 2836  generator and C or C++ are the input languages. A single target
 2837  language must be specified when SWIG is run. This results in generating
 2838  code for C/C++ and the specified target language to interface with each
 2839  other. SWIG can be invoked multiple times, but with a different target
 2840  language specified on each invocation. This ability to interface C/C++
 2841  to many different target languages is one of SWIG's core strengths and
 2842  features.</p>
 2843 <p> SWIG is very broadly composed of two components. A core component
 2844  creates a parse tree from the input ISO C/C++ and SWIG directives
 2845  (extensions to the C/C++ standards). The parse tree is then passed to a
 2846  second component, one of the target language modules for generating
 2847  code specific to a higher level language. SWIG supports many different
 2848  target languages. These target languages are given a status of either
 2849  Supported or Experimental. This status is provided to indicate the
 2850  level of maturity to expect when using a particular target language as
 2851  not all target languages are fully developed.</p>
 2852 <p> The second part of the SWIG documentation contains a chapter for
 2853  each target level language. Each chapter will state the status
 2854  (Supported or Experimental) for that language.</p>
 2855 <h3><a name="Introduction_supported_status">2.3.1 Supported status</a></h3>
 2856 <p> A target language is given the 'Supported' status when</p>
 2857 <ul>
 2858 <li>It is in a mature, well functioning state.</li>
 2859 <li>It has its own comprehensive chapter in the documentation.</li>
 2860 <li>It passes all of the main SWIG test-suite and has a range of working
 2861  examples.</li>
 2862 <li>It supports the vast majority of SWIG features.</li>
 2863 <li>It provides strong backwards compatibility between releases.</li>
 2864 </ul>
 2865 <p> The above is a short summary and further details are outlined in the
 2866  <a href="#Extending_supported_status">Supported status</a> section in
 2867  the Extending chapter. The good news is that all the well-known and
 2868  most popular languages have this status.</p>
 2869 <h3><a name="Introduction_experimental_status">2.3.2 Experimental status</a>
 2870 </h3>
 2871 <p> A target language is given the 'Experimental' status when</p>
 2872 <ul>
 2873 <li>It is of sub-standard quality, failing to meet the above 'Supported'
 2874  status.</li>
 2875 <li>It is somewhere between the mid to mature stage of development.</li>
 2876 <li>It does not guarantee any backwards compatibility between releases.</li>
 2877 <li>It is in need of help to finish development.</li>
 2878 </ul>
 2879 <p> Anyone using an experimental target language is strongly urged to
 2880  assist with development of the target language module if they wish to
 2881  use it.</p>
 2882 <p> SWIG displays a warning when an experimental target language is used
 2883  in order to set expectations and emphasize the experimental status of
 2884  the target language. The usual <a href="#Warnings_suppression">warning
 2885  suppression</a> techniques can be used if required.</p>
 2886 <p> The above is a short summary and further details are outlined in the
 2887  <a href="#Extending_experimental_status">Experimental status</a>
 2888  section in the Extending chapter.</p>
 2889 <h2><a name="Introduction_nn4">2.4 A SWIG example</a></h2>
 2890 <p> The best way to illustrate SWIG is with a simple example. Consider
 2891  the following C code:</p>
 2892 <div class="code">
 2893 <pre>
 2894 /* File : example.c */
 2896 double My_variable = 3.0;
 2898 /* Compute factorial of n */
 2899 int fact(int n) {
 2900   if (n &lt;= 1)
 2901     return 1;
 2902   else
 2903     return n*fact(n-1);
 2904 }
 2906 /* Compute n mod m */
 2907 int my_mod(int n, int m) {
 2908   return(n % m);
 2909 }
 2910 </pre>
 2911 </div>
 2912 <p> Suppose that you wanted to access these functions and the global
 2913  variable <tt>My_variable</tt> from Tcl. You start by making a SWIG
 2914  interface file as shown below (by convention, these files carry a .i
 2915  suffix) :</p>
 2916 <h3><a name="Introduction_nn5">2.4.1 SWIG interface file</a></h3>
 2917 <div class="code">
 2918 <pre>
 2919 /* File : example.i */
 2920 %module example
 2921 %{
 2922 /* Put headers and other declarations here */
 2923 extern double My_variable;
 2924 extern int    fact(int);
 2925 extern int    my_mod(int n, int m);
 2926 %}
 2928 extern double My_variable;
 2929 extern int    fact(int);
 2930 extern int    my_mod(int n, int m);
 2931 </pre>
 2932 </div>
 2933 <p> The interface file contains ISO C function prototypes and variable
 2934  declarations. The <tt>%module</tt> directive defines the name of the
 2935  module that will be created by SWIG. The <tt>%{ %}</tt> block provides
 2936  a location for inserting additional code, such as C header files or
 2937  additional C declarations, into the generated C wrapper code.</p>
 2938 <h3><a name="Introduction_nn6">2.4.2 The swig command</a></h3>
 2939 <p> SWIG is invoked using the <tt>swig</tt> command. We can use this to
 2940  build a Tcl module (under Linux) as follows :</p>
 2941 <div class="shell">
 2942 <pre>
 2943 unix &gt; <b>swig -tcl example.i</b>
 2944 unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b>
 2945 unix &gt; <b>gcc -shared example.o example_wrap.o -o example.so</b>
 2946 unix &gt; <b>tclsh</b>
 2947 % <b>load ./example.so</b>
 2948 % <b>fact 4</b>
 2949 24
 2950 % <b>my_mod 23 7</b>
 2951 2
 2952 % <b>expr $My_variable + 4.5</b>
 2953 7.5
 2954 %
 2955 </pre>
 2956 </div>
 2957 <p> The <tt>swig</tt> command produced a new file called <tt>
 2958 example_wrap.c</tt> that should be compiled along with the <tt>example.c</tt>
 2959  file. Most operating systems and scripting languages now support
 2960  dynamic loading of modules. In our example, our Tcl module has been
 2961  compiled into a shared library that can be loaded into Tcl. When
 2962  loaded, Tcl can now access the functions and variables declared in the
 2963  SWIG interface. A look at the file <tt>example_wrap.c</tt> reveals a
 2964  hideous mess. However, you almost never need to worry about it.</p>
 2965 <h3><a name="Introduction_nn7">2.4.3 Building a Perl5 module</a></h3>
 2966 <p> Now, let's turn these functions into a Perl5 module. Without making
 2967  any changes type the following (shown for Solaris):</p>
 2968 <div class="shell">
 2969 <pre>
 2970 unix &gt; <b>swig -perl5 example.i</b>
 2971 unix &gt; <b>gcc -c example.c example_wrap.c \
 2972         -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
 2973 unix &gt; <b>ld -G example.o example_wrap.o -o example.so</b> # This is for Solaris
 2974 unix &gt; <b>perl5.003
 2975 use example;
 2976 print example::fact(4), &quot;\n&quot;;
 2977 print example::my_mod(23, 7), &quot;\n&quot;;
 2978 print $example::My_variable + 4.5, &quot;\n&quot;;
 2979 &lt;ctrl-d&gt;</b>
 2980 24
 2981 2
 2982 7.5
 2983 unix &gt;
 2984 </pre>
 2985 </div>
 2986 <h3><a name="Introduction_nn8">2.4.4 Building a Python module</a></h3>
 2987 <p> Finally, let's build a module for Python (shown for Irix).</p>
 2988 <div class="shell">
 2989 <pre>
 2990 unix &gt; <b>swig -python example.i</b>
 2991 unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b>
 2992 unix &gt; <b>gcc -shared example.o example_wrap.o -o _example.so</b>
 2993 unix &gt; <b>python</b>
 2994 Python 2.0 (#6, Feb 21 2001, 13:29:45)
 2995 [GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
 2996 Type &quot;copyright&quot;, &quot;credits&quot; or &quot;license&quot; for more information.     
 2997 &gt;&gt;&gt; <b>import example</b>
 2998 &gt;&gt;&gt; <b>example.fact(4)</b>
 2999 24
 3000 &gt;&gt;&gt; <b>example.my_mod(23, 7)</b>
 3001 2
 3002 &gt;&gt;&gt; <b>example.cvar.My_variable + 4.5</b>
 3003 7.5
 3004 </pre>
 3005 </div>
 3006 <h3><a name="Introduction_nn9">2.4.5 Shortcuts</a></h3>
 3007 <p> To the truly lazy programmer, one may wonder why we needed the extra
 3008  interface file at all. As it turns out, you can often do without it.
 3009  For example, you could also build a Perl5 module by just running SWIG
 3010  on the C header file and specifying a module name as follows</p>
 3011 <div class="shell">
 3012 <pre>
 3013 unix &gt; <b>swig -perl5 -module example example.h</b>
 3014 unix &gt; <b>gcc -c example.c example_wrap.c \
 3015         -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
 3016 unix &gt; <b>ld -G example.o example_wrap.o -o example.so</b>
 3017 unix &gt; <b>perl5.003
 3018 use example;
 3019 print example::fact(4), &quot;\n&quot;;
 3020 print example::my_mod(23, 7), &quot;\n&quot;;
 3021 print $example::My_variable + 4.5, &quot;\n&quot;;
 3022 &lt;ctrl-d&gt;</b>
 3023 24
 3024 2
 3025 7.5
 3026 </pre>
 3027 </div>
 3028 <h2><a name="Introduction_nn10">2.5 Supported C/C++ language features</a>
 3029 </h2>
 3030 <p> A primary goal of the SWIG project is to make the language binding
 3031  process extremely easy. Although a few simple examples have been shown,
 3032  SWIG is quite capable in supporting most of C++. Some of the major
 3033  features include:</p>
 3034 <ul>
 3035 <li>Full C99 preprocessing.</li>
 3036 <li>All ISO C and C++ datatypes.</li>
 3037 <li>Functions, variables, and constants.</li>
 3038 <li>Classes.</li>
 3039 <li>Single and multiple inheritance.</li>
 3040 <li>Overloaded functions and methods.</li>
 3041 <li>Overloaded operators.</li>
 3042 <li>C++ templates (including member templates, specialization, and
 3043  partial specialization).</li>
 3044 <li>Namespaces.</li>
 3045 <li>Variable length arguments.</li>
 3046 <li>C++ smart pointers.</li>
 3047 </ul>
 3048 <p> Most of C++11 is also supported. Details are in the <a href="#CPlusPlus11">
 3049 C++11</a> chapter. C++14 support is covered in the <a href="#CPlusPlus14">
 3050 C++14</a> chapter. C++17 support is covered in the <a href="#CPlusPlus17">
 3051 C++17</a> chapter. C++20 support is covered in the <a href="#CPlusPlus20">
 3052 C++20</a> chapter.</p>
 3053 <p> It is important to stress that SWIG is not a simplistic C++ lexing
 3054  tool like several apparently similar wrapper generation tools. SWIG not
 3055  only parses C++, it implements the full C++ type system and it is able
 3056  to understand C++ semantics. SWIG generates its wrappers with full
 3057  knowledge of this information. As a result, you will find SWIG to be
 3058  just as capable of dealing with nasty corner cases as it is in wrapping
 3059  simple C++ code. In fact, SWIG is able to handle C++ code that stresses
 3060  the very limits of many C++ compilers.</p>
 3061 <h2><a name="Introduction_nn11">2.6 Non-intrusive interface building</a></h2>
 3062 <p> When used as intended, SWIG requires minimal (if any) modification
 3063  to existing C or C++ code. This makes SWIG extremely easy to use with
 3064  existing packages and promotes software reuse and modularity. By making
 3065  the C/C++ code independent of the high level interface, you can change
 3066  the interface and reuse the code in other applications. It is also
 3067  possible to support different types of interfaces depending on the
 3068  application.</p>
 3069 <h2><a name="Introduction_build_system">2.7 Incorporating SWIG into a
 3070  build system</a></h2>
 3071 <p> SWIG is a command line tool and as such can be incorporated into any
 3072  build system that supports invoking external tools/compilers. SWIG is
 3073  most commonly invoked from within a Makefile, but is also known to be
 3074  invoked from popular IDEs such as Microsoft Visual Studio.</p>
 3075 <p> If you are using the GNU Autotools (<a href="https://www.gnu.org/software/autoconf/">
 3076 Autoconf</a>/ <a href="https://www.gnu.org/software/automake/">Automake</a>
 3077 / <a href="https://www.gnu.org/software/libtool/">Libtool</a>) to
 3078  configure SWIG use in your project, the SWIG Autoconf macros can be
 3079  used. The primary macro is <tt>ax_pkg_swig</tt>, see <a href="https://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">
 3080 http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig
 3081 </a>. The <tt>ax_python_devel</tt> macro is also helpful for generating
 3082  Python extensions. See the <a href="https://www.gnu.org/software/autoconf-archive/">
 3083 Autoconf Archive</a> for further information on this and other Autoconf
 3084  macros.</p>
 3085 <p> There is growing support for SWIG in some build tools, for example <a
 3086 href="https://cmake.org">CMake</a> is a cross-platform, open-source
 3087  build manager with built in support for SWIG. CMake can detect the SWIG
 3088  executable and many of the target language libraries for linking
 3089  against. CMake knows how to build shared libraries and loadable modules
 3090  on many different operating systems. This allows easy cross platform
 3091  SWIG development. It can also generate the custom commands necessary
 3092  for driving SWIG from IDEs and makefiles. All of this can be done from
 3093  a single cross platform input file. The following example is a CMake
 3094  input file for creating a Python wrapper for the SWIG interface file,
 3095  example.i:</p>
 3096 <div class="code">
 3097 <pre>
 3099 # This is a CMake example for Python
 3104 FIND_PACKAGE(PythonLibs)
 3109 SET(CMAKE_SWIG_FLAGS &quot;&quot;)
 3112 SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS &quot;-includeall&quot;)
 3113 SWIG_ADD_MODULE(example python example.i example.cxx)
 3116 </pre>
 3117 </div>
 3118 <p> The above example will generate native build files such as
 3119  makefiles, nmake files and Visual Studio projects which will invoke
 3120  SWIG and compile the generated C++ files into _example.so (UNIX) or
 3121  _example.pyd (Windows). For other target languages on Windows a dll,
 3122  instead of a .pyd file, is usually generated.</p>
 3123 <h2><a name="Introduction_nn12">2.8 Hands off code generation</a></h2>
 3124 <p> SWIG is designed to produce working code that needs no
 3125  hand-modification (in fact, if you look at the output, you probably
 3126  won't want to modify it). You should think of your target language
 3127  interface being defined entirely by the input to SWIG, not the
 3128  resulting output file. While this approach may limit flexibility for
 3129  hard-core hackers, it allows others to forget about the low-level
 3130  implementation details.</p>
 3131 <h2><a name="Introduction_nn13">2.9 SWIG and freedom</a></h2>
 3132 <p> No, this isn't a special section on the sorry state of world
 3133  politics. However, it may be useful to know that SWIG was written with
 3134  a certain &quot;philosophy&quot; about programming---namely that programmers are
 3135  smart and that tools should just stay out of their way. Because of
 3136  that, you will find that SWIG is extremely permissive in what it lets
 3137  you get away with. In fact, you can use SWIG to go well beyond
 3138  &quot;shooting yourself in the foot&quot; if dangerous programming is your goal.
 3139  On the other hand, this kind of freedom may be exactly what is needed
 3140  to work with complicated and unusual C/C++ applications.</p>
 3141 <p> Ironically, the freedom that SWIG provides is countered by an
 3142  extremely conservative approach to code generation. At its core, SWIG
 3143  tries to distill even the most advanced C++ code down to a small
 3144  well-defined set of interface building techniques based on ISO C
 3145  programming. Because of this, you will find that SWIG interfaces can be
 3146  easily compiled by virtually every C/C++ compiler and that they can be
 3147  used on any platform. Again, this is an important part of staying out
 3148  of the programmer's way----the last thing any developer wants to do is
 3149  to spend their time debugging the output of a tool that relies on
 3150  non-portable or unreliable programming features. Dependencies are often
 3151  a source of incompatibilities and problems and so additional third
 3152  party libraries are not used in the generated code. SWIG will also
 3153  generally avoid generating code that introduces a dependency on the C++
 3154  Standard Template Library (STL). SWIG will generate code that depends
 3155  on the C libraries though.</p>
 3156 <HR NOSHADE>
 3157 <h1><a name="Windows">3 Getting started on Windows</a></h1>
 3159 <!-- INDEX -->
 3160 <div class="sectiontoc">
 3161 <ul>
 3162 <li><a href="#Windows_installation">Installation on Windows</a>
 3163 <ul>
 3164 <li><a href="#Windows_executable">Windows Executable</a></li>
 3165 </ul>
 3166 </li>
 3167 <li><a href="#Windows_examples">SWIG Windows Examples</a>
 3168 <ul>
 3169 <li><a href="#Windows_visual_studio">Instructions for using the Examples
 3170  with Visual Studio</a>
 3171 <ul>
 3172 <li><a href="#Windows_csharp">C#</a></li>
 3173 <li><a href="#Windows_java">Java</a></li>
 3174 <li><a href="#Windows_perl">Perl</a></li>
 3175 <li><a href="#Windows_python">Python</a></li>
 3176 <li><a href="#Windows_tcl">TCL</a></li>
 3177 <li><a href="#Windows_r">R</a></li>
 3178 <li><a href="#Windows_ruby">Ruby</a></li>
 3179 </ul>
 3180 </li>
 3181 <li><a href="#Windows_other_compilers">Instructions for using the
 3182  Examples with other compilers</a></li>
 3183 </ul>
 3184 </li>
 3185 <li><a href="#Windows_swig_exe">Building swig.exe on Windows</a>
 3186 <ul>
 3187 <li><a href="#Windows_cmake">Building swig.exe using CMake</a></li>
 3188 <li><a href="#Windows_msys2">Building swig.exe using MSYS2</a></li>
 3189 <li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
 3190 </li>
 3191 <li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a>
 3192 <ul>
 3193 <li><a href="#Windows_examples_cygwin">Running the examples on Windows
 3194  using Cygwin</a></li>
 3195 </ul>
 3196 </li>
 3197 </ul>
 3198 </li>
 3199 <li><a href="#Windows_interface_file">Microsoft extensions and other
 3200  Windows quirks</a></li>
 3201 </ul>
 3202 </div>
 3203 <!-- INDEX -->
 3204 <p> This chapter describes SWIG usage on Microsoft Windows. Installing
 3205  SWIG and running the examples is covered as well as building the SWIG
 3206  executable. Usage within the Unix like environments MinGW and Cygwin is
 3207  also detailed.</p>
 3208 <h2><a name="Windows_installation">3.1 Installation on Windows</a></h2>
 3209 <p> SWIG does not come with the usual Windows type installation program,
 3210  however it is quite easy to get started. The main steps are:</p>
 3211 <ul>
 3212 <li>Download the swigwin zip package from the <a href="https://www.swig.org">
 3213 SWIG website</a> and unzip into a directory. This is all that needs
 3214  downloading for the Windows platform.</li>
 3215 <li>Set environment variables as described in the <a href="#Windows_examples">
 3216 SWIG Windows Examples</a> section in order to run examples using Visual
 3217  C++.</li>
 3218 </ul>
 3219 <h3><a name="Windows_executable">3.1.1 Windows Executable</a></h3>
 3220 <p> The swigwin distribution contains the SWIG Windows 32-bit
 3221  executable, swig.exe, which will run on both 32-bit and 64-bit versions
 3222  of Windows. If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe">
 3223 Building swig.exe on Windows</a>.</p>
 3224 <h2><a name="Windows_examples">3.2 SWIG Windows Examples</a></h2>
 3225 <p> Microsoft Visual C++ is the most commonly used compiler for
 3226  compiling and linking SWIG's output on Windows. The Examples directory
 3227  has a few Visual C++ project files (.dsp files). These were produced by
 3228  Visual C++ 6. Newer versions of Visual Studio are able to open and
 3229  convert these project files. Each C# example comes with a Visual Studio
 3230  2005 solution and associated project files instead of Visual C++ 6
 3231  project files. The project files have been set up to execute SWIG in a
 3232  custom build rule for the SWIG interface (.i) file. Alternatively run
 3233  the <a href="#Windows_examples_cygwin">examples using Cygwin</a>.</p>
 3234 <p> More information on each of the examples is available with the
 3235  examples distributed with SWIG (Examples/index.html).</p>
 3236 <h3><a name="Windows_visual_studio">3.2.1 Instructions for using the
 3237  Examples with Visual Studio</a></h3>
 3238 <p> Ensure the SWIG executable is as supplied in the SWIG root directory
 3239  in order for the examples to work. Most languages require some
 3240  environment variables to be set<b> before</b> running Visual C++. Note
 3241  that Visual C++ must be re-started to pick up any changes in
 3242  environment variables. Open up an example .dsp file, Visual C++ will
 3243  prompt you to upgrade the project and convert it into an MSBuild
 3244  project (.vcxproj file) and Solution (.sln file). Note that older
 3245  versions of Visual C++ will simply create a workspace for you (.dsw
 3246  file). Ensure the Release build is selected then do a Rebuild Solution
 3247  from the Build menu. The required environment variables are displayed
 3248  with their current values during the build.</p>
 3249 <p> The list of required environment variables for each module language
 3250  is also listed below. They are usually set from the Control Panel and
 3251  System properties, but this depends on which flavour of Windows you are
 3252  running. If you don't want to use environment variables then change all
 3253  occurrences of the environment variables in the .dsp files with hard
 3254  coded values. If you are interested in how the project files are set up
 3255  there is explanatory information in some of the language module's
 3256  documentation.</p>
 3257 <h4><a name="Windows_csharp"> C#</a></h4>
 3258 <p> The C# examples do not require any environment variables to be set
 3259  as a C# project file is included. Just open up the .sln solution file
 3260  in Visual Studio 2005 or later, select Release Build, and do a Rebuild
 3261  Solution from the Build menu. The accompanying C# and C++ project files
 3262  are automatically used by the solution file.</p>
 3263 <h4><a name="Windows_java"> Java</a></h4>
 3264 <p><b> <tt>JAVA_INCLUDE</tt></b> : Set this to the directory containing
 3265  jni.h
 3266 <br><b> <tt>JAVA_BIN</tt></b> : Set this to the bin directory containing
 3267  javac.exe</p>
 3268 <p> Example using JDK1.3:
 3269 <br> <tt>JAVA_INCLUDE: D:\jdk1.3\include
 3270 <br> JAVA_BIN: D:\jdk1.3\bin
 3271 <br></tt></p>
 3272 <h4><a name="Windows_perl"> Perl</a></h4>
 3273 <p><b> <tt>PERL5_INCLUDE</tt></b> : Set this to the directory containing
 3274  perl.h
 3275 <br><b> <tt>PERL5_LIB</tt></b> : Set this to the Perl library including
 3276  path for linking</p>
 3277 <p> Example using nsPerl 5.004_04:</p>
 3278 <p> <tt>PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE
 3279 <br> PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib
 3280 <br></tt></p>
 3281 <h4><a name="Windows_python"> Python</a></h4>
 3282 <p><b> <tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that
 3283  contains Python.h
 3284 <br><b> <tt>PYTHON_LIB</tt></b> : Set this to the Python library
 3285  including path for linking</p>
 3286 <p> Example using Python 2.1.1:
 3287 <br> <tt>PYTHON_INCLUDE: D:\python21\include
 3288 <br> PYTHON_LIB: D:\python21\libs\python21.lib
 3289 <br></tt></p>
 3290 <h4><a name="Windows_tcl"> TCL</a></h4>
 3291 <p><b> <tt>TCL_INCLUDE</tt></b> : Set this to the directory containing
 3292  tcl.h
 3293 <br><b> <tt>TCL_LIB</tt></b> : Set this to the TCL library including
 3294  path for linking</p>
 3295 <p> Example using ActiveTcl
 3296 <br> <tt>TCL_INCLUDE: D:\tcl\include
 3297 <br> TCL_LIB: D:\tcl\lib\tcl83.lib
 3298 <br></tt></p>
 3299 <h4><a name="Windows_r"> R</a></h4>
 3300 <p><b> <tt>R_INCLUDE</tt></b> : Set this to the directory containing R.h
 3301 <br><b> <tt>R_LIB</tt></b> : Set this to the R library (Rdll.lib)
 3302  including path for linking. The library needs to be built as described
 3303  in the R README.packages file (the pexports.exe approach is the
 3304  easiest).</p>
 3305 <p> Example using R 2.5.1:
 3306 <br> <tt>R_INCLUDE: C:\Program Files\R\R-2.5.1\include
 3307 <br> R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib
 3308 <br></tt></p>
 3309 <h4><a name="Windows_ruby"> Ruby</a></h4>
 3310 <p><b> <tt>RUBY_INCLUDE</tt></b> : Set this to the directory containing
 3311  ruby.h
 3312 <br><b> <tt>RUBY_LIB</tt></b> : Set this to the ruby library including
 3313  path for linking</p>
 3314 <p> Example using Ruby 1.6.4:
 3315 <br> <tt>RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32
 3316 <br> RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib
 3317 <br></tt></p>
 3318 <h3><a name="Windows_other_compilers">3.2.2 Instructions for using the
 3319  Examples with other compilers</a></h3>
 3320 <p> If you do not have access to Visual C++ you will have to set up
 3321  project files / Makefiles for your chosen compiler. There is a section
 3322  in each of the language modules detailing what needs setting up using
 3323  Visual C++ which may be of some guidance. Alternatively you may want to
 3324  use Cygwin as described in the following section.</p>
 3325 <h2><a name="Windows_swig_exe">3.3 Building swig.exe on Windows</a></h2>
 3326 <p> The SWIG distribution provides a pre-built swig.exe and so it is not
 3327  necessary for users to build the SWIG executable. However, this section
 3328  is provided for those that want to modify the SWIG source code in a
 3329  Windows environment. Normally this is not needed, so most people will
 3330  want to ignore this section.</p>
 3331 <p> There are various ways to build the SWIG executable including <a href="https://cmake.org/">
 3332 CMake</a> which is able to generate project files for building with
 3333  Visual Studio. SWIG can also be compiled and run using <a href="https://www.msys2.org/">
 3334 MSYS2</a>, <a href="https://www.cygwin.com">Cygwin</a> or <a href="https://osdn.net/projects/mingw/">
 3335 MinGW</a>, all of which provide a Unix like front end to Windows and
 3336  comes free with the gcc C/C++ compiler.</p>
 3337 <h3><a name="Windows_cmake">3.3.1 Building swig.exe using CMake</a></h3>
 3338 <p> SWIG can be built using <a href="https://cmake.org/">CMake</a> and
 3339  Visual Studio rather than autotools. As with the other approaches to
 3340  building SWIG the dependencies need to be installed. The steps below
 3341  are one of a number of ways of installing the dependencies without
 3342  requiring Cygwin or MinGW. For fully working build steps always check
 3343  the Continuous Integration (CI) setups currently detailed in the <a href="https://github.com/swig/swig/tree/master/.github/workflows/nuget.yml">
 3344 GitHub Actions YAML file</a>.</p>
 3345 <ol>
 3346 <li> Install Nuget from <a href="https://www.nuget.org/downloads">
 3347 https://www.nuget.org/downloads</a> (v6.0.0 is used in this example, and
 3348  installed to <tt>C:\Tools</tt>). Nuget is the package manager for .NET,
 3349  but allows us to easily install <a href="https://cmake.org/">CMake</a>
 3350  and other dependencies required by SWIG.</li>
 3351 <li> Install <a href="https://www.nuget.org/packages/CMake-win64/">
 3352 CMake-win64 Nuget package</a> using the following command:
 3353 <pre>C:\Tools\nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake</pre>
 3354  Using PowerShell the equivalent syntax is:
 3355 <pre>&amp; &quot;C:\Tools\nuget&quot; install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake</pre>
 3356  Alternatively you can download CMake from <a href="https://cmake.org/download/">
 3357 https://cmake.org/download/</a>.</li>
 3358 <li> Install the <a href="https://www.nuget.org/packages/bison/">Bison
 3359  Nuget package</a> using the following command:
 3360 <pre>C:\Tools\nuget install Bison -Version 3.7.4 -OutputDirectory C:\Tools\bison</pre>
 3361  Alternatively download Bison from <a href="https://sourceforge.net/projects/winflexbison/files/">
 3362 https://sourceforge.net/projects/winflexbison/files/</a> (Bison 3.7.4 is
 3363  used in this example) and save to a folder e.g. <tt>C:\Tools\Bison</tt></li>
 3364 <li> Install the <a href="https://www.nuget.org/packages/pcre2/">PCRE2
 3365  Nuget package</a> using the following command:
 3366 <pre>C:\Tools\nuget install PCRE2 -Version 10.39 -OutputDirectory C:\Tools\pcre2</pre>
 3367  Note this is a x64 build, if this is not suitable PCRE2 can be built
 3368  from source using <a href="https://github.com/PhilipHazel/pcre2/">
 3369 https://github.com/PhilipHazel/pcre2/</a>. Alternatively, set <tt>
 3370 WITH_PCRE=OFF</tt> to disable PCRE2 support if you are sure you do not
 3371  require it.</li>
 3372 <li> We will also need the SWIG source code. Either download a zipped
 3373  archive from GitHub, or if git is installed clone the latest codebase
 3374  using:
 3375 <pre>git clone https://github.com/swig/swig.git</pre>
 3376  In this example we are assuming the source code is available at <tt>
 3377 C:\swig</tt></li>
 3378 <li>
 3379 <p> Now we have all the required dependencies we can build SWIG using
 3380  PowerShell and the commands below. We are assuming Visual Studio 2019
 3381  is installed. For other versions of Visual Studio change <tt>&quot;Visual
 3382  Studio 16 2019 -A x64&quot;</tt> to the relevant <a href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators">
 3383 Visual Studio Generator</a> and architecture. We add the required build
 3384  tools to the system PATH, and then build a Release version of SWIG. If
 3385  all runs successfully a new swig.exe should be generated in the <tt>
 3386 C:/swig/install2/bin</tt> folder.</p>
 3387 </li>
 3388 </ol>
 3389 <div class="shell">
 3390 <pre>
 3391 cd C:\swig
 3393 $env:PATH=&quot;C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;&quot; + $env:PATH
 3394 $PCRE_ROOT=&quot;C:\Tools\pcre2\PCRE2.10.39.0&quot;
 3395 $PCRE_PLATFORM=&quot;x64&quot;
 3397 cmake -G &quot;Visual Studio 16 2019&quot; -A &quot;x64&quot; `
 3398 -DCMAKE_INSTALL_PREFIX=&quot;C:/swig/install2&quot; `
 3399 -DCMAKE_C_FLAGS=&quot;/DPCRE2_STATIC&quot; `
 3400 -DCMAKE_CXX_FLAGS=&quot;/DPCRE2_STATIC&quot; `
 3401 -DPCRE2_INCLUDE_DIR=&quot;$PCRE_ROOT/include&quot; `
 3402 -DPCRE2_LIBRARY=&quot;$PCRE_ROOT/lib/pcre2-8-static.lib&quot; `
 3403 -S . -B build
 3405 cmake --build build --config Release
 3406 cmake --install build --config Release
 3408 # to test the exe built correctly
 3409 cd install2/bin
 3410 ./swig.exe -version
 3411 ./swig.exe -help
 3412 </pre>
 3413 </div>
 3414 <p> In addition to Release builds you can create a Debug build using:</p>
 3415 <div class="shell">
 3416 <pre>cmake --build build --config Debug</pre>
 3417 </div>
 3418 <p> A Visual Studio solution file should be generated named swig.sln.
 3419  This can be opened and debugged by running the swig project and setting
 3420  <tt>Properties &gt; Debugging &gt; Command Arguments</tt>. For example to
 3421  debug one of the test-suite .i files included with the SWIG source use
 3422  the following:</p>
 3423 <div class="shell">
 3424 <pre>-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i</pre>
 3425 </div>
 3426 <h3><a name="Windows_msys2">3.3.2 Building swig.exe using MSYS2</a></h3>
 3427 <p> Download and install MSYS2 from <a href="https://www.msys2.org/">
 3428 www.msys2.org</a> (tested with version msys2-x86_64-20201109). Launch
 3429  the MSYS2 shell.</p>
 3430 <p> Install the packages needed to build swig:
 3431 <br></p>
 3432 <div class="shell">
 3433 <pre>
 3434 pacman -S git autoconf automake bison gcc make pcre2-devel
 3435 </pre>
 3436 </div>
 3437 <p> Clone the repository to /usr/src/:</p>
 3438 <div class="shell">
 3439 <pre>
 3440 mkdir /usr/src/
 3441 cd /usr/src/
 3442 git clone https://github.com/swig/swig.git
 3443 </pre>
 3444 </div>
 3445 <p> Configure and build:</p>
 3446 <div class="shell">
 3447 <pre>
 3448 cd /usr/src/swig
 3449 ./autogen.sh
 3450 ./configure
 3451 make
 3452 </pre>
 3453 </div>
 3454 <p> Finally you may also want to install SWIG:</p>
 3455 <div class="shell">
 3456 <pre>
 3457 make install
 3458 </pre>
 3459 </div>
 3460 <h3><a name="Windows_mingw_msys">3.3.3 Building swig.exe using MinGW and
 3461  MSYS</a></h3>
 3462 <p> The short abbreviated instructions follow...</p>
 3463 <ul>
 3464 <li>Install MinGW and MSYS from the <a href="https://osdn.net/projects/mingw/">
 3465 MinGW</a> site. This provides a Unix environment on Windows.</li>
 3466 <li>Follow the usual Unix instructions in the README file in the SWIG
 3467  root directory to build swig.exe from the MinGW command prompt.</li>
 3468 </ul>
 3469 <p> The step by step instructions to download and install MinGW and
 3470  MSYS, then download and build the latest version of SWIG from Github
 3471  follow... Note that the instructions for obtaining SWIG from Github are
 3472  also online at <a href="https://www.swig.org/svn.html">SWIG Bleeding
 3473  Edge</a>.</p>
 3474 <p><b> Pitfall note:</b> Execute the steps in the order shown and don't
 3475  use spaces in path names. In fact it is best to use the default
 3476  installation directories.</p>
 3477 <ol>
 3478 <li> Download the following packages from the <a href="https://osdn.net/projects/mingw/releases/">
 3479 MinGW download page</a>. Note that at the time of writing, the majority
 3480  of these are in the Current release list and some are in the Snapshot
 3481  or Previous release list.
 3482 <ul>
 3483 <li>MinGW-3.1.0-1.exe</li>
 3484 <li>MSYS-1.0.11-2004.04.30-1.exe</li>
 3485 <li>msysDTK-1.0.1.exe</li>
 3486 <li>bison-2.0-MSYS.tar.gz</li>
 3487 <li>msys-autoconf-2.59.tar.bz2</li>
 3488 <li>msys-automake-1.8.2.tar.bz2</li>
 3489 </ul>
 3490 </li>
 3491 <li> Install MinGW-3.1.0-1.exe (C:\MinGW is default location.)</li>
 3492 <li> Install MSYS-1.0.11-2004.04.30-1.exe. Make sure you install it on
 3493  the same windows drive letter as MinGW (C:\msys\1.0 is default). In the
 3494  post install script,
 3495 <ul>
 3496 <li>Answer y to the &quot;do you wish to continue with the post install?&quot;</li>
 3497 <li>Answer y to the &quot;do you have MinGW installed?&quot;</li>
 3498 <li>Type in the folder in which you installed MinGW (C:/MinGW is
 3499  default)</li>
 3500 </ul>
 3501 </li>
 3502 <li> Install msysDTK-1.0.1.exe to the same folder that you installed
 3503  MSYS (C:\msys\1.0 is default).</li>
 3504 <li> Copy the following to the MSYS install folder (C:\msys\1.0 is
 3505  default):
 3506 <ul>
 3507 <li>msys-automake-1.8.2.tar.bz2</li>
 3508 <li>msys-autoconf-2.59.tar.bz2</li>
 3509 <li>bison-2.0-MSYS.tar.gz</li>
 3510 </ul>
 3511 </li>
 3512 <li> Start the MSYS command prompt and execute:<div class="shell">
 3513 <pre>
 3514 cd /
 3515 tar -jxf msys-automake-1.8.2.tar.bz2
 3516 tar -jxf msys-autoconf-2.59.tar.bz2
 3517 tar -zxf bison-2.0-MSYS.tar.gz
 3518 </pre>
 3519 </div></li>
 3520 <li> The very latest development version of SWIG is available from <a href="https://github.com/swig/swig">
 3521 SWIG on Github</a> and can be downloaded as a zip file or if you have
 3522  Git installed, via Git. Either download the latest <a href="https://github.com/swig/swig/archive/master.zip">
 3523 Zip file</a> snapshot and unzip and rename the top level folder to
 3524  /usr/src/swig. Otherwise if using Git, type in the following:<div class="shell">
 3525 <pre>
 3526 mkdir /usr/src
 3527 cd /usr/src
 3528 git clone https://github.com/swig/swig.git
 3529 </pre>
 3530 </div><b> Pitfall note:</b> If you want to place SWIG in a different
 3531  folder to the proposed /usr/src/swig, do not use MSYS emulated windows
 3532  drive letters, because the autotools will fail miserably on those.</li>
 3533 <li> The PCRE2 third party library needs to be built next. Download the
 3534  latest PCRE2 source tarball, such as <tt>pcre2-10.39.tar.bz2</tt>, from
 3535  <a href="https://www.pcre.org">www.pcre.org</a> and place in the <tt>
 3536 /usr/src/swig</tt> directory. Build PCRE2 as a static library using the
 3537  Tools/pcre-build.sh script as follows:<div class="shell">
 3538 <pre>
 3539 cd /usr/src/swig
 3540 Tools/pcre-build.sh
 3541 </pre>
 3542 </div></li>
 3543 <li> You are now ready to build SWIG. Execute the following commands to
 3544  build swig.exe:<div class="shell">
 3545 <pre>
 3546 cd /usr/src/swig
 3547 ./autogen.sh
 3548 ./configure
 3549 make
 3550 </pre>
 3551 </div></li>
 3552 </ol>
 3553 <h3><a name="Windows_cygwin">3.3.4 Building swig.exe using Cygwin</a></h3>
 3554 <p> Note that SWIG can also be built using Cygwin. However, SWIG will
 3555  then require the Cygwin DLL when executing. Follow the Unix
 3556  instructions in the README file in the SWIG root directory. Note that
 3557  the Cygwin environment will also allow one to regenerate the autotool
 3558  generated files which are supplied with the release distribution. These
 3559  files are generated using the <tt>autogen.sh</tt> script and will only
 3560  need regenerating in circumstances such as changing the build system.</p>
 3561 <h4><a name="Windows_examples_cygwin"> Running the examples on
 3562  Windows using Cygwin</a></h4>
 3563 <p> The examples and test-suite work as successfully on Cygwin as on any
 3564  other Unix operating system. The modules which are known to work are
 3565  Python, Tcl, Perl, Ruby, Java and C#. Follow the Unix instructions in
 3566  the README file in the SWIG root directory to build the examples.</p>
 3567 <h2><a name="Windows_interface_file">3.4 Microsoft extensions and other
 3568  Windows quirks</a></h2>
 3569 <p> A common problem when using SWIG on Windows are the Microsoft
 3570  function calling conventions which are not in the C++ standard. SWIG
 3571  parses ISO C/C++ so cannot deal with proprietary conventions such as <tt>
 3572 __declspec(dllimport)</tt>, <tt>__stdcall</tt> etc. There is a Windows
 3573  interface file, <tt>windows.i</tt>, to deal with these calling
 3574  conventions though. The file also contains typemaps for handling
 3575  commonly used Windows specific types such as <tt>__int64</tt>, <tt>BOOL</tt>
 3576 , <tt>DWORD</tt> etc. Include it like you would any other interface
 3577  file, for example:</p>
 3578 <div class="code">
 3579 <pre>
 3580 %include &lt;windows.i&gt;
 3582 __declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);
 3583 </pre>
 3584 </div>
 3585 <p>Note that if you follow Microsoft's recommendation of wrapping the <tt>
 3586 __declspec</tt> calls in a preprocessor definition, you will need to
 3587  make sure that the definition is included by SWIG as well, by either
 3588  defining it manually or via a header. For example, if you have
 3589  specified the preprocessor definition in a header named <tt>
 3590 export_lib.h</tt> and include other headers which depend on it, you
 3591  should use the <tt>%include</tt> directive to include the definition
 3592  explicitly. For example, if you had a header file, <tt>bar.h</tt>,
 3593  which depended on <tt>export_lib.h</tt>, your SWIG definition file
 3594  might look like:</p>
 3595 <div class="code">
 3596 <pre>
 3597 // bar.i
 3598 %module bar
 3599 %include &lt;windows.i&gt;
 3600 %include &quot;export_lib.h&quot;
 3601 %include &quot;bar.h&quot;
 3602 </pre>
 3603 </div>
 3604 <p> where export_lib.h may contain:</p>
 3605 <div class="code">
 3606 <pre>
 3607 // export_lib.h
 3608 #define BAR_API __declspec(dllexport)
 3609 </pre>
 3610 </div>
 3611 <p> and bar.h may look like:</p>
 3612 <div class="code">
 3613 <pre>
 3614 // bar.h
 3615 #include &quot;export_lib.h&quot;
 3616 BAR_API void bar_function(int, double);
 3617 </pre>
 3618 </div>
 3619 <p> Using the preprocessor to remove BAR_API is a popular simpler
 3620  solution:</p>
 3621 <div class="code">
 3622 <pre>
 3623 // bar.i
 3624 %module bar
 3625 #define BAR_API
 3626 %include &quot;bar.h&quot;
 3627 </pre>
 3628 </div><HR NOSHADE>
 3629 <h1><a name="Scripting">4 Scripting Languages</a></h1>
 3631 <!-- INDEX -->
 3632 <div class="sectiontoc">
 3633 <ul>
 3634 <li><a href="#Scripting_nn2">The two language view of the world</a></li>
 3635 <li><a href="#Scripting_nn3">How does a scripting language talk to C?</a>
 3636 <ul>
 3637 <li><a href="#Scripting_nn4">Wrapper functions</a></li>
 3638 <li><a href="#Scripting_nn5">Variable linking</a></li>
 3639 <li><a href="#Scripting_nn6">Constants</a></li>
 3640 <li><a href="#Scripting_nn7">Structures and classes</a></li>
 3641 <li><a href="#Scripting_nn8">Proxy classes</a></li>
 3642 </ul>
 3643 </li>
 3644 <li><a href="#Scripting_nn9">Building scripting language extensions</a>
 3645 <ul>
 3646 <li><a href="#Scripting_nn10">Shared libraries and dynamic loading</a></li>
 3647 <li><a href="#Scripting_nn11">Linking with shared libraries</a></li>
 3648 <li><a href="#Scripting_nn12">Static linking</a></li>
 3649 </ul>
 3650 </li>
 3651 </ul>
 3652 </div>
 3653 <!-- INDEX -->
 3654 <p> This chapter provides a brief overview of scripting language
 3655  extension programming and the mechanisms by which scripting language
 3656  interpreters access C and C++ code.</p>
 3657 <h2><a name="Scripting_nn2">4.1 The two language view of the world</a></h2>
 3658 <p> When a scripting language is used to control a C program, the
 3659  resulting system tends to look as follows:</p>
 3660 <center><img alt="Scripting language input - C/C++ functions output" HEIGHT="149"
 3661 src="ch2.1.png" WIDTH="377"></center>
 3662 <p> In this programming model, the scripting language interpreter is
 3663  used for high level control whereas the underlying functionality of the
 3664  C/C++ program is accessed through special scripting language
 3665  &quot;commands.&quot; If you have ever tried to write your own simple command
 3666  interpreter, you might view the scripting language approach to be a
 3667  highly advanced implementation of that. Likewise, If you have ever used
 3668  a package such as MATLAB or IDL, it is a very similar model--the
 3669  interpreter executes user commands and scripts. However, most of the
 3670  underlying functionality is written in a low-level language like C or
 3671  Fortran.</p>
 3672 <p> The two-language model of computing is extremely powerful because it
 3673  exploits the strengths of each language. C/C++ can be used for maximal
 3674  performance and complicated systems programming tasks. Scripting
 3675  languages can be used for rapid prototyping, interactive debugging,
 3676  scripting, and access to high-level data structures such associative
 3677  arrays.</p>
 3678 <h2><a name="Scripting_nn3">4.2 How does a scripting language talk to C?</a>
 3679 </h2>
 3680 <p> Scripting languages are built around a parser that knows how to
 3681  execute commands and scripts. Within this parser, there is a mechanism
 3682  for executing commands and accessing variables. Normally, this is used
 3683  to implement the builtin features of the language. However, by
 3684  extending the interpreter, it is usually possible to add new commands
 3685  and variables. To do this, most languages define a special API for
 3686  adding new commands. Furthermore, a special foreign function interface
 3687  defines how these new commands are supposed to hook into the
 3688  interpreter.</p>
 3689 <p> Typically, when you add a new command to a scripting interpreter you
 3690  need to do two things; first you need to write a special &quot;wrapper&quot;
 3691  function that serves as the glue between the interpreter and the
 3692  underlying C function. Then you need to give the interpreter
 3693  information about the wrapper by providing details about the name of
 3694  the function, arguments, and so forth. The next few sections illustrate
 3695  the process.</p>
 3696 <h3><a name="Scripting_nn4">4.2.1 Wrapper functions</a></h3>
 3697 <p> Suppose you have an ordinary C function like this :</p>
 3698 <div class="code">
 3699 <pre>
 3700 int fact(int n) {
 3701   if (n &lt;= 1)
 3702     return 1;
 3703   else
 3704     return n*fact(n-1);
 3705 }
 3706 </pre>
 3707 </div>
 3708 <p> In order to access this function from a scripting language, it is
 3709  necessary to write a special &quot;wrapper&quot; function that serves as the glue
 3710  between the scripting language and the underlying C function. A wrapper
 3711  function must do three things :</p>
 3712 <ul>
 3713 <li>Gather function arguments and make sure they are valid.</li>
 3714 <li>Call the C function.</li>
 3715 <li>Convert the return value into a form recognized by the scripting
 3716  language.</li>
 3717 </ul>
 3718 <p> As an example, the Tcl wrapper function for the <tt>fact()</tt>
 3719  function above example might look like the following :</p>
 3720 <div class="code">
 3721 <pre>
 3722 int wrap_fact(ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]) {
 3723   int result;
 3724   int arg0;
 3725   if (argc != 2) {
 3726     interp-&gt;result = &quot;wrong # args&quot;;
 3727     return TCL_ERROR;
 3728   }
 3729   arg0 = atoi(argv[1]);
 3730   result = fact(arg0);
 3731   sprintf(interp-&gt;result, &quot;%d&quot;, result);
 3732   return TCL_OK;
 3733 }
 3735 </pre>
 3736 </div>
 3737 <p> Once you have created a wrapper function, the final step is to tell
 3738  the scripting language about the new function. This is usually done in
 3739  an initialization function called by the language when the module is
 3740  loaded. For example, adding the above function to the Tcl interpreter
 3741  requires code like the following :</p>
 3742 <div class="code">
 3743 <pre>
 3744 int Wrap_Init(Tcl_Interp *interp) {
 3745   Tcl_CreateCommand(interp, &quot;fact&quot;, wrap_fact, (ClientData) NULL,
 3746                     (Tcl_CmdDeleteProc *) NULL);
 3747   return TCL_OK;
 3748 }
 3749 </pre>
 3750 </div>
 3751 <p> When executed, Tcl will now have a new command called &quot;<tt>fact</tt>
 3752 &quot; that you can use like any other Tcl command.</p>
 3753 <p> Although the process of adding a new function to Tcl has been
 3754  illustrated, the procedure is almost identical for Perl and Python.
 3755  Both require special wrappers to be written and both need additional
 3756  initialization code. Only the specific details are different.</p>
 3757 <h3><a name="Scripting_nn5">4.2.2 Variable linking</a></h3>
 3758 <p> Variable linking refers to the problem of mapping a C/C++ global
 3759  variable to a variable in the scripting language interpreter. For
 3760  example, suppose you had the following variable:</p>
 3761 <div class="code">
 3762 <pre>
 3763 double Foo = 3.5;
 3764 </pre>
 3765 </div>
 3766 <p> It might be nice to access it from a script as follows (shown for
 3767  Perl):</p>
 3768 <div class="targetlang">
 3769 <pre>
 3770 $a = $Foo * 2.3;   # Evaluation
 3771 $Foo = $a + 2.0;   # Assignment
 3772 </pre>
 3773 </div>
 3774 <p> To provide such access, variables are commonly manipulated using a
 3775  pair of get/set functions. For example, whenever the value of a
 3776  variable is read, a &quot;get&quot; function is invoked. Similarly, whenever the
 3777  value of a variable is changed, a &quot;set&quot; function is called.</p>
 3778 <p> In many languages, calls to the get/set functions can be attached to
 3779  evaluation and assignment operators. Therefore, evaluating a variable
 3780  such as <tt>$Foo</tt> might implicitly call the get function.
 3781  Similarly, typing <tt>$Foo = 4</tt> would call the underlying set
 3782  function to change the value.</p>
 3783 <h3><a name="Scripting_nn6">4.2.3 Constants</a></h3>
 3784 <p> In many cases, a C program or library may define a large collection
 3785  of constants. For example:</p>
 3786 <div class="code">
 3787 <pre>
 3788 #define RED   0xff0000
 3789 #define BLUE  0x0000ff
 3790 #define GREEN 0x00ff00
 3791 </pre>
 3792 </div>
 3793 <p> To make constants available, their values can be stored in scripting
 3794  language variables such as <tt>$RED</tt>, <tt>$BLUE</tt>, and <tt>
 3795 $GREEN</tt>. Virtually all scripting languages provide C functions for
 3796  creating variables so installing constants is usually a trivial
 3797  exercise.</p>
 3798 <h3><a name="Scripting_nn7">4.2.4 Structures and classes</a></h3>
 3799 <p> Although scripting languages have no trouble accessing simple
 3800  functions and variables, accessing C/C++ structures and classes present
 3801  a different problem. This is because the implementation of structures
 3802  is largely related to the problem of data representation and layout.
 3803  Furthermore, certain language features are difficult to map to an
 3804  interpreter. For instance, what does C++ inheritance mean in a Perl
 3805  interface?</p>
 3806 <p> The most straightforward technique for handling structures is to
 3807  implement a collection of accessor functions that hide the underlying
 3808  representation of a structure. For example,</p>
 3809 <div class="code">
 3810 <pre>
 3811 struct Vector {
 3812   Vector();
 3813   ~Vector();
 3814   double x, y, z;
 3815 };
 3817 </pre>
 3818 </div>
 3819 <p> can be transformed into the following set of functions :</p>
 3820 <div class="code">
 3821 <pre>
 3822 Vector *new_Vector();
 3823 void delete_Vector(Vector *v);
 3824 double Vector_x_get(Vector *v);
 3825 double Vector_y_get(Vector *v);
 3826 double Vector_z_get(Vector *v);
 3827 void Vector_x_set(Vector *v, double x);
 3828 void Vector_y_set(Vector *v, double y);
 3829 void Vector_z_set(Vector *v, double z);
 3831 </pre>
 3832 </div>
 3833 <p> Now, from an interpreter these function might be used as follows:</p>
 3834 <div class="targetlang">
 3835 <pre>
 3836 % set v [new_Vector]
 3837 % Vector_x_set $v 3.5
 3838 % Vector_y_get $v
 3839 % delete_Vector $v
 3840 % ...
 3841 </pre>
 3842 </div>
 3843 <p> Since accessor functions provide a mechanism for accessing the
 3844  internals of an object, the interpreter does not need to know anything
 3845  about the actual representation of a <tt>Vector</tt>.</p>
 3846 <h3><a name="Scripting_nn8">4.2.5 Proxy classes</a></h3>
 3847 <p> In certain cases, it is possible to use the low-level accessor
 3848  functions to create a proxy class, also known as a shadow class. A
 3849  proxy class is a special kind of object that gets created in a
 3850  scripting language to access a C/C++ class (or struct) in a way that
 3851  looks like the original structure (that is, it proxies the real C++
 3852  class). For example, if you have the following C++ definition :</p>
 3853 <div class="code">
 3854 <pre>
 3855 class Vector {
 3856 public:
 3857   Vector();
 3858   ~Vector();
 3859   double x, y, z;
 3860 };
 3861 </pre>
 3862 </div>
 3863 <p> A proxy classing mechanism would allow you to access the structure
 3864  in a more natural manner from the interpreter. For example, in Python,
 3865  you might want to do this:</p>
 3866 <div class="targetlang">
 3867 <pre>
 3868 &gt;&gt;&gt; v = Vector()
 3869 &gt;&gt;&gt; v.x = 3
 3870 &gt;&gt;&gt; v.y = 4
 3871 &gt;&gt;&gt; v.z = -13
 3872 &gt;&gt;&gt; ...
 3873 &gt;&gt;&gt; del v
 3874 </pre>
 3875 </div>
 3876 <p> Similarly, in Perl5 you may want the interface to work like this:</p>
 3877 <div class="targetlang">
 3878 <pre>
 3879 $v = new Vector;
 3880 $v-&gt;{x} = 3;
 3881 $v-&gt;{y} = 4;
 3882 $v-&gt;{z} = -13;
 3884 </pre>
 3885 </div>
 3886 <p> Finally, in Tcl :</p>
 3887 <div class="targetlang">
 3888 <pre>
 3889 Vector v
 3890 v configure -x 3 -y 4 -z -13
 3892 </pre>
 3893 </div>
 3894 <p> When proxy classes are used, two objects are really at work--one in
 3895  the scripting language, and an underlying C/C++ object. Operations
 3896  affect both objects equally and for all practical purposes, it appears
 3897  as if you are simply manipulating a C/C++ object.</p>
 3898 <h2><a name="Scripting_nn9">4.3 Building scripting language extensions</a>
 3899 </h2>
 3900 <p> The final step in using a scripting language with your C/C++
 3901  application is adding your extensions to the scripting language itself.
 3902  There are two primary approaches for doing this. The preferred
 3903  technique is to build a dynamically loadable extension in the form of a
 3904  shared library. Alternatively, you can recompile the scripting language
 3905  interpreter with your extensions added to it.</p>
 3906 <h3><a name="Scripting_nn10">4.3.1 Shared libraries and dynamic loading</a>
 3907 </h3>
 3908 <p> To create a shared library or DLL, you often need to look at the
 3909  manual pages for your compiler and linker. However, the procedure for a
 3910  few common platforms is shown below:</p>
 3911 <div class="shell">
 3912 <pre>
 3913 # Build a shared library for Solaris
 3914 gcc -fpic -c example.c example_wrap.c -I/usr/local/include
 3915 ld -G example.o example_wrap.o -o example.so
 3917 # Build a shared library for Linux
 3918 gcc -fpic -c example.c example_wrap.c -I/usr/local/include
 3919 gcc -shared example.o example_wrap.o -o example.so
 3920 </pre>
 3921 </div>
 3922 <p> To use your shared library, you simply use the corresponding command
 3923  in the scripting language (load, import, use, etc...). This will import
 3924  your module and allow you to start using it. For example:</p>
 3925 <div class="targetlang">
 3926 <pre>
 3927 % load ./example.so
 3928 % fact 4
 3929 24
 3930 %
 3931 </pre>
 3932 </div>
 3933 <p> When working with C++ codes, the process of building shared
 3934  libraries may be more complicated--primarily due to the fact that C++
 3935  modules may need additional code in order to operate correctly. On many
 3936  machines, you can build a shared C++ module by following the above
 3937  procedures, but changing the link line to the following :</p>
 3938 <div class="shell">
 3939 <pre>
 3940 c++ -shared example.o example_wrap.o -o example.so
 3941 </pre>
 3942 </div>
 3943 <h3><a name="Scripting_nn11">4.3.2 Linking with shared libraries</a></h3>
 3944 <p> When building extensions as shared libraries, it is not uncommon for
 3945  your extension to rely upon other shared libraries on your machine. In
 3946  order for the extension to work, it needs to be able to find all of
 3947  these libraries at run-time. Otherwise, you may get an error such as
 3948  the following :</p>
 3949 <div class="targetlang">
 3950 <pre>
 3951 &gt;&gt;&gt; import graph
 3952 Traceback (innermost last):
 3953   File &quot;&lt;stdin&gt;&quot;, line 1, in ?
 3954   File &quot;/home/sci/data1/beazley/graph/graph.py&quot;, line 2, in ?
 3955     import graphc
 3956 ImportError:  1101:/home/sci/data1/beazley/bin/python: rld: Fatal Error: cannot 
 3957 successfully map soname 'libgraph.so' under any of the filenames /usr/lib/libgraph.so:/
 3958 lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
 3959 &gt;&gt;&gt;
 3960 </pre>
 3961 </div>
 3962 <p> What this error means is that the extension module created by SWIG
 3963  depends upon a shared library called &quot;<tt>libgraph.so</tt>&quot; that the
 3964  system was unable to locate. To fix this problem, there are a few
 3965  approaches you can take.</p>
 3966 <ul>
 3967 <li>Link your extension and explicitly tell the linker where the
 3968  required libraries are located. Often times, this can be done with a
 3969  special linker flag such as <tt>-R</tt>, <tt>-rpath</tt>, etc. This is
 3970  not implemented in a standard manner so read the man pages for your
 3971  linker to find out more about how to set the search path for shared
 3972  libraries.</li>
 3973 <li>Put shared libraries in the same directory as the executable. This
 3974  technique is sometimes required for correct operation on non-Unix
 3975  platforms.</li>
 3976 <li>Set the UNIX environment variable <tt>LD_LIBRARY_PATH</tt> to the
 3977  directory where shared libraries are located before running Python.
 3978  Although this is an easy solution, it is not recommended. Consider
 3979  setting the path using linker options instead.</li>
 3980 </ul>
 3981 <h3><a name="Scripting_nn12">4.3.3 Static linking</a></h3>
 3982 <p> With static linking, you rebuild the scripting language interpreter
 3983  with extensions. The process usually involves compiling a short main
 3984  program that adds your customized commands to the language and starts
 3985  the interpreter. You then link your program with a library to produce a
 3986  new scripting language executable.</p>
 3987 <p> Although static linking is supported on all platforms, this is not
 3988  the preferred technique for building scripting language extensions. In
 3989  fact, there are very few practical reasons for doing this--consider
 3990  using shared libraries instead.</p>
 3991 <HR NOSHADE>
 3992 <h1><a name="SWIG">5 SWIG Basics</a></h1>
 3994 <!-- INDEX -->
 3995 <div class="sectiontoc">
 3996 <ul>
 3997 <li><a href="#SWIG_nn2">Running SWIG</a>
 3998 <ul>
 3999 <li><a href="#SWIG_nn3">Input format</a></li>
 4000 <li><a href="#SWIG_output">SWIG Output</a></li>
 4001 <li><a href="#SWIG_nn5">Comments</a></li>
 4002 <li><a href="#SWIG_nn6">C Preprocessor</a></li>
 4003 <li><a href="#SWIG_nn7">SWIG Directives</a></li>
 4004 <li><a href="#SWIG_nn8">Parser Limitations</a></li>
 4005 </ul>
 4006 </li>
 4007 <li><a href="#SWIG_nn9">Wrapping Simple C Declarations</a>
 4008 <ul>
 4009 <li><a href="#SWIG_nn10">Basic Type Handling</a></li>
 4010 <li><a href="#SWIG_nn11">Global Variables</a></li>
 4011 <li><a href="#SWIG_nn12">Constants</a></li>
 4012 <li><a href="#SWIG_nn13">A brief word about const</a></li>
 4013 <li><a href="#SWIG_nn14">A cautionary tale of char *</a></li>
 4014 </ul>
 4015 </li>
 4016 <li><a href="#SWIG_nn15">Pointers and complex objects</a>
 4017 <ul>
 4018 <li><a href="#SWIG_nn16">Simple pointers</a></li>
 4019 <li><a href="#SWIG_nn17">Run time pointer type checking</a></li>
 4020 <li><a href="#SWIG_nn18">Derived types, structs, and classes</a></li>
 4021 <li><a href="#SWIG_nn19">Undefined datatypes</a></li>
 4022 <li><a href="#SWIG_nn20">Typedef</a></li>
 4023 </ul>
 4024 </li>
 4025 <li><a href="#SWIG_nn21">Other Practicalities</a>
 4026 <ul>
 4027 <li><a href="#SWIG_nn22">Passing structures by value</a></li>
 4028 <li><a href="#SWIG_nn23">Return by value</a></li>
 4029 <li><a href="#SWIG_nn24">Linking to structure variables</a></li>
 4030 <li><a href="#SWIG_nn25">Linking to char *</a></li>
 4031 <li><a href="#SWIG_nn26">Arrays</a></li>
 4032 <li><a href="#SWIG_readonly_variables">Creating read-only variables</a></li>
 4033 <li><a href="#SWIG_rename_ignore">Renaming and ignoring declarations</a>
 4034 <ul>
 4035 <li><a href="#SWIG_nn29">Simple renaming of specific identifiers</a></li>
 4036 <li><a href="#SWIG_ignore">Ignoring identifiers</a></li>
 4037 <li><a href="#SWIG_advanced_renaming">Advanced renaming support</a></li>
 4038 <li><a href="#SWIG_limiting_renaming">Limiting global renaming rules</a></li>
 4039 <li><a href="#SWIG_chosen_unignore">Ignoring everything then wrapping a
 4040  few selected symbols</a></li>
 4041 </ul>
 4042 </li>
 4043 <li><a href="#SWIG_default_args">Default/optional arguments</a></li>
 4044 <li><a href="#SWIG_nn30">Pointers to functions and callbacks</a></li>
 4045 </ul>
 4046 </li>
 4047 <li><a href="#SWIG_nn31">Structures and unions</a>
 4048 <ul>
 4049 <li><a href="#SWIG_nn32">Typedef and structures</a></li>
 4050 <li><a href="#SWIG_nn33">Character strings and structures</a></li>
 4051 <li><a href="#SWIG_nn34">Array members</a></li>
 4052 <li><a href="#SWIG_structure_data_members">Structure data members</a></li>
 4053 <li><a href="#SWIG_nn36">C constructors and destructors</a></li>
 4054 <li><a href="#SWIG_adding_member_functions">Adding member functions to C
 4055  structures</a></li>
 4056 <li><a href="#SWIG_nested_structs">Nested structures</a></li>
 4057 <li><a href="#SWIG_nn39">Other things to note about structure wrapping</a>
 4058 </li>
 4059 </ul>
 4060 </li>
 4061 <li><a href="#SWIG_nn40">Code Insertion</a>
 4062 <ul>
 4063 <li><a href="#SWIG_nn41">The output of SWIG</a></li>
 4064 <li><a href="#SWIG_nn42">Code insertion blocks</a></li>
 4065 <li><a href="#SWIG_nn43">Inlined code blocks</a></li>
 4066 <li><a href="#SWIG_nn44">Initialization blocks</a></li>
 4067 </ul>
 4068 </li>
 4069 <li><a href="#SWIG_nn45">An Interface Building Strategy</a>
 4070 <ul>
 4071 <li><a href="#SWIG_nn46">Preparing a C program for SWIG</a></li>
 4072 <li><a href="#SWIG_nn47">The SWIG interface file</a></li>
 4073 <li><a href="#SWIG_nn48">Why use separate interface files?</a></li>
 4074 <li><a href="#SWIG_nn49">Getting the right header files</a></li>
 4075 <li><a href="#SWIG_nn50">What to do with main()</a></li>
 4076 </ul>
 4077 </li>
 4078 </ul>
 4079 </div>
 4080 <!-- INDEX -->
 4081 <p> This chapter describes the basic operation of SWIG, the structure of
 4082  its input files, and how it handles standard ISO C declarations. C++
 4083  support is described in the next chapter. However, C++ programmers
 4084  should still read this chapter to understand the basics. Specific
 4085  details about each target language are described in later chapters.</p>
 4086 <h2><a name="SWIG_nn2">5.1 Running SWIG</a></h2>
 4087 <p> To run SWIG, use the <tt>swig</tt> command with options and a
 4088  filename like this:</p>
 4089 <div class="shell">
 4090 <pre>
 4091 swig [ options ] filename
 4092 </pre>
 4093 </div>
 4094 <p> where <tt>filename</tt> is a SWIG interface file or a C/C++ header
 4095  file. Full help can be seen by running <tt>swig -help</tt>. Below is
 4096  the common set of options that can be used. Additional options are also
 4097  defined for each target language. A full list can be obtained by
 4098  running <tt>swig<em> -&lt;lang&gt;</em> -help</tt> for language<em> &lt;lang&gt;</em>
 4099  specific options, for example, <tt>swig -ruby -help</tt> for Ruby.</p>
 4100 <div class="shell">
 4101 <pre>
 4102 Supported Target Language Options
 4103      -csharp         - Generate C# wrappers
 4104      -d              - Generate D wrappers
 4105      -go             - Generate Go wrappers
 4106      -guile          - Generate Guile wrappers
 4107      -java           - Generate Java wrappers
 4108      -javascript     - Generate Javascript wrappers
 4109      -lua            - Generate Lua wrappers
 4110      -octave         - Generate Octave wrappers
 4111      -perl5          - Generate Perl 5 wrappers
 4112      -php7           - Generate PHP 7 or later wrappers
 4113      -python         - Generate Python wrappers
 4114      -r              - Generate R (aka GNU S) wrappers
 4115      -ruby           - Generate Ruby wrappers
 4116      -scilab         - Generate Scilab wrappers
 4117      -tcl8           - Generate Tcl 8 wrappers
 4118      -xml            - Generate XML wrappers
 4120 Experimental Target Language Options
 4121      -mzscheme       - Generate MzScheme/Racket wrappers
 4122      -ocaml          - Generate OCaml wrappers
 4124 General Options
 4125      -addextern      - Add extra extern declarations
 4126      -c++            - Enable C++ processing
 4127      -co &lt;file&gt;      - Check &lt;file&gt; out of the SWIG library
 4128      -copyctor       - Automatically generate copy constructors wherever possible
 4129      -cpperraswarn   - Treat the preprocessor #error statement as #warning (default)
 4130      -cppext &lt;ext&gt;   - Change file extension of generated C++ files to &lt;ext&gt;
 4131                        (default is cxx)
 4132      -copyright      - Display copyright notices
 4133      -debug-classes  - Display information about the classes found in the interface
 4134      -debug-module &lt;n&gt;- Display module parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
 4135      -debug-symtabs  - Display symbol tables information
 4136      -debug-symbols  - Display target language symbols in the symbol tables
 4137      -debug-csymbols - Display C symbols in the symbol tables
 4138      -debug-lsymbols - Display target language layer symbols
 4139      -debug-quiet    - Display less parse tree node debug info when using other -debug options
 4140      -debug-tags     - Display information about the tags found in the interface
 4141      -debug-template - Display information for debugging templates
 4142      -debug-top &lt;n&gt;  - Display entire parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
 4143      -debug-typedef  - Display information about the types and typedefs in the interface
 4144      -debug-typemap  - Display typemap debugging information
 4145      -debug-tmsearch - Display typemap search debugging information
 4146      -debug-tmused   - Display typemaps used debugging information
 4147      -directors      - Turn on director mode for all the classes, mainly for testing
 4148      -dirprot        - Turn on wrapping of protected members for director classes (default)
 4149      -D&lt;symbol&gt;      - Define a symbol &lt;symbol&gt; (for conditional compilation)
 4150      -E              - Preprocess only, does not generate wrapper code
 4151      -external-runtime [file] - Export the SWIG runtime stack
 4152      -fakeversion &lt;v&gt;- Make SWIG fake the program version number to &lt;v&gt;
 4153      -fcompact       - Compile in compact mode
 4154      -features &lt;list&gt;- Set global features, where &lt;list&gt; is a comma separated list of
 4155                        features, eg -features directors,autodoc=1
 4156                        If no explicit value is given to the feature, a default of 1 is used
 4157      -fastdispatch   - Enable fast dispatch mode to produce faster overload dispatcher code
 4158      -Fmicrosoft     - Display error/warning messages in Microsoft format
 4159      -Fstandard      - Display error/warning messages in commonly used format
 4160      -fvirtual       - Compile in virtual elimination mode
 4161      -help           - Display help
 4162      -I-             - Don't search the current directory
 4163      -I&lt;dir&gt;         - Look for SWIG files in directory &lt;dir&gt;
 4164      -ignoremissing  - Ignore missing include files
 4165      -importall      - Follow all #include statements as imports
 4166      -includeall     - Follow all #include statements
 4167      -l&lt;ifile&gt;       - Include SWIG library file &lt;ifile&gt;
 4168      -macroerrors    - Report errors inside macros
 4169      -makedefault    - Create default constructors/destructors (the default)
 4170      -M              - List all dependencies
 4171      -MD             - Is equivalent to `-M -MF &lt;file&gt;', except `-E' is not implied
 4172      -MF &lt;file&gt;      - Generate dependencies into &lt;file&gt; and continue generating wrappers
 4173      -MM             - List dependencies, but omit files in SWIG library
 4174      -MMD            - Like `-MD', but omit files in SWIG library
 4175      -module &lt;name&gt;  - Set module name to &lt;name&gt;
 4176      -MP             - Generate phony targets for all dependencies
 4177      -MT &lt;target&gt;    - Set the target of the rule emitted by dependency generation
 4178      -nocontract     - Turn off contract checking
 4179      -nocpperraswarn - Do not treat the preprocessor #error statement as #warning
 4180      -nodefault      - Do not generate default constructors nor default destructors
 4181      -nodefaultctor  - Do not generate implicit default constructors
 4182      -nodefaultdtor  - Do not generate implicit default destructors
 4183      -nodirprot      - Do not wrap director protected members
 4184      -noexcept       - Do not wrap exception specifiers
 4185      -nofastdispatch - Disable fast dispatch mode (default)
 4186      -nopreprocess   - Skip the preprocessor step
 4187      -notemplatereduce - Disable reduction of the typedefs in templates
 4188      -O              - Enable the optimization options:
 4189                         -fastdispatch -fvirtual
 4190      -o &lt;outfile&gt;    - Set name of C/C++ output file to &lt;outfile&gt;
 4191      -oh &lt;headfile&gt;  - Set name of C++ output header file for directors to &lt;headfile&gt;
 4192      -outcurrentdir  - Set default output dir to current dir instead of input file's path
 4193      -outdir &lt;dir&gt;   - Set language specific files output directory to &lt;dir&gt;
 4194      -pcreversion    - Display PCRE2 version information
 4195      -small          - Compile in virtual elimination and compact mode
 4196      -swiglib        - Report location of SWIG library and exit
 4197      -templatereduce - Reduce all the typedefs in templates
 4198      -v              - Run in verbose mode
 4199      -version        - Display SWIG version number
 4200      -Wall           - Remove all warning suppression, also implies -Wextra
 4201      -Wallkw         - Enable keyword warnings for all the supported languages
 4202      -Werror         - Treat warnings as errors
 4203      -Wextra         - Adds the following additional warnings: 309,403,405,512,321,322
 4204      -w&lt;list&gt;        - Suppress/add warning messages, eg -w401,+321 - see Warnings.html
 4205      -xmlout &lt;file&gt;  - Write XML version of the parse tree to &lt;file&gt; after normal processing
 4206 </pre>
 4207 </div>
 4208 <p> Arguments may also be passed in a command-line options file (also
 4209  known as a response file) which is useful if they exceed the system
 4210  command line length limit. To do this, put the arguments in a file,
 4211  then provide the file name prefixed with <tt>@</tt> like so:</p>
 4212 <div class="shell">
 4213 <pre>
 4214 swig @<em>file</em>
 4215 </pre>
 4216 </div>
 4217 <p> The options read from the file are inserted in place of the file
 4218  option. If the file does not exist, or cannot be read, then the option
 4219  will be treated literally and not removed.</p>
 4220 <p> Options in the file are separated by whitespace. A whitespace
 4221  character may be included in an option by surrounding the entire option
 4222  in either single or double quotes. Any character (including a
 4223  backslash) may be included by prefixing the character to be included
 4224  with a backslash. The file may itself contain additional <tt>@file</tt>
 4225  options; any such options will be processed recursively.</p>
 4226 <h3><a name="SWIG_nn3">5.1.1 Input format</a></h3>
 4227 <p> As input, SWIG expects a file containing ISO C/C++ declarations and
 4228  special SWIG directives. More often than not, this is a special SWIG
 4229  interface file which is usually denoted with a special <tt>.i</tt> or <tt>
 4230 .swg</tt> suffix. In certain cases, SWIG can be used directly on raw
 4231  header files or source files. However, this is not the most typical
 4232  case and there are several reasons why you might not want to do this
 4233  (described later).</p>
 4234 <p> The most common format of a SWIG interface is as follows:</p>
 4235 <div class="code">
 4236 <pre>
 4237 %module mymodule 
 4238 %{
 4239 #include &quot;myheader.h&quot;
 4240 %}
 4241 // Now list ISO C/C++ declarations
 4242 int foo;
 4243 int bar(int x);
 4244 ...
 4245 </pre>
 4246 </div>
 4247 <p> The module name is supplied using the special <tt>%module</tt>
 4248  directive. Modules are described further in the <a href="#Modules_introduction">
 4249 Modules Introduction</a> section.</p>
 4250 <p> Everything in the <tt>%{ ... %}</tt> block is simply copied verbatim
 4251  to the resulting wrapper file created by SWIG. This section is almost
 4252  always used to include header files and other declarations that are
 4253  required to make the generated wrapper code compile. It is important to
 4254  emphasize that just because you include a declaration in a SWIG input
 4255  file, that declaration does<em> not</em> automatically appear in the
 4256  generated wrapper code---therefore you need to make sure you include
 4257  the proper header files in the <tt>%{ ... %}</tt> section. It should be
 4258  noted that the text enclosed in <tt>%{ ... %}</tt> is not parsed or
 4259  interpreted by SWIG. The <tt>%{...%}</tt> syntax and semantics in SWIG
 4260  is analogous to that of the declarations section used in input files to
 4261  parser generation tools such as yacc or bison.</p>
 4262 <h3><a name="SWIG_output">5.1.2 SWIG Output</a></h3>
 4263 <p> The output of SWIG is a C/C++ file that contains all of the wrapper
 4264  code needed to build an extension module. SWIG may generate some
 4265  additional files depending on the target language. By default, an input
 4266  file with the name <tt>file.i</tt> is transformed into a file <tt>
 4267 file_wrap.c</tt> or <tt>file_wrap.cxx</tt> (depending on whether or not
 4268  the <tt>-c++</tt> option has been used). The name of the output C/C++
 4269  file can be changed using the <tt>-o</tt> option. In certain cases,
 4270  file suffixes are used by the compiler to determine the source language
 4271  (C, C++, etc.). Therefore, you have to use the <tt>-o</tt> option to
 4272  change the suffix of the SWIG-generated wrapper file if you want
 4273  something different than the default. For example:</p>
 4274 <div class="shell">
 4275 <pre>
 4276 $ swig -c++ -python -o example_wrap.cpp example.i
 4277 </pre>
 4278 </div>
 4279 <p> The C/C++ output file created by SWIG often contains everything that
 4280  is needed to construct an extension module for the target scripting
 4281  language. SWIG is not a stub compiler nor is it usually necessary to
 4282  edit the output file (and if you look at the output, you probably won't
 4283  want to). To build the final extension module, the SWIG output file is
 4284  compiled and linked with the rest of your C/C++ program to create a
 4285  shared library.</p>
 4286 <p> For many target languages SWIG will also generate proxy class files
 4287  in the target language. The default output directory for these language
 4288  specific files is the same directory as the generated C/C++ file. This
 4289  can be modified using the <tt>-outdir</tt> option. For example:</p>
 4290 <div class="shell">
 4291 <pre>
 4292 $ swig -c++ -python -outdir pyfiles -o cppfiles/example_wrap.cpp example.i
 4293 </pre>
 4294 </div>
 4295 <p> If the directories <tt>cppfiles</tt> and <tt>pyfiles</tt> exist, the
 4296  following will be generated:</p>
 4297 <div class="shell">
 4298 <pre>
 4299 cppfiles/example_wrap.cpp
 4300 pyfiles/example.py
 4301 </pre>
 4302 </div>
 4303 <p> If the <tt>-outcurrentdir</tt> option is used (without <tt>-o</tt>)
 4304  then SWIG behaves like a typical C/C++ compiler and the default output
 4305  directory is then the current directory. Without this option the
 4306  default output directory is the path to the input file. If <tt>-o</tt>
 4307  and <tt>-outcurrentdir</tt> are used together, <tt>-outcurrentdir</tt>
 4308  is effectively ignored as the output directory for the language files
 4309  is the same directory as the generated C/C++ file if not overridden
 4310  with <tt>-outdir</tt>.</p>
 4311 <h3><a name="SWIG_nn5">5.1.3 Comments</a></h3>
 4312 <p> C and C++ style comments may appear anywhere in interface files. In
 4313  previous versions of SWIG, comments were used to generate documentation
 4314  files. However, this feature is currently under repair and will
 4315  reappear in a later SWIG release.</p>
 4316 <h3><a name="SWIG_nn6">5.1.4 C Preprocessor</a></h3>
 4317 <p> Like C, SWIG preprocesses all input files through an enhanced
 4318  version of the C preprocessor. All standard preprocessor features are
 4319  supported including file inclusion, conditional compilation and macros.
 4320  However, <tt>#include</tt> statements are ignored unless the <tt>
 4321 -includeall</tt> command line option has been supplied. The reason for
 4322  disabling includes is that SWIG is sometimes used to process raw C
 4323  header files. In this case, you usually only want the extension module
 4324  to include functions in the supplied header file rather than everything
 4325  that might be included by that header file (i.e., system headers, C
 4326  library functions, etc.).</p>
 4327 <p> It should also be noted that the SWIG preprocessor skips all text
 4328  enclosed inside a <tt>%{...%}</tt> block. In addition, the preprocessor
 4329  includes a number of macro handling enhancements that make it more
 4330  powerful than the normal C preprocessor. These extensions are described
 4331  in the &quot;<a href="#Preprocessor">Preprocessor</a>&quot; chapter.</p>
 4332 <h3><a name="SWIG_nn7">5.1.5 SWIG Directives</a></h3>
 4333 <p> Most of SWIG's operation is controlled by special directives that
 4334  are always preceded by a &quot;<tt>%</tt>&quot; to distinguish them from normal C
 4335  declarations. These directives are used to give SWIG hints or to alter
 4336  SWIG's parsing behavior in some manner.</p>
 4337 <p> Since SWIG directives are not legal C syntax, it is generally not
 4338  possible to include them in header files. However, SWIG directives can
 4339  be included in C header files using conditional compilation like this:</p>
 4340 <div class="code">
 4341 <pre>
 4342 /* header.h  --- Some header file */
 4344 /* SWIG directives -- only seen if SWIG is running */ 
 4345 #ifdef SWIG
 4346 %module foo
 4347 #endif
 4348 </pre>
 4349 </div>
 4350 <p> <tt>SWIG</tt> is a special preprocessing symbol defined by SWIG when
 4351  it is parsing an input file.</p>
 4352 <h3><a name="SWIG_nn8">5.1.6 Parser Limitations</a></h3>
 4353 <p> Although SWIG can parse most C/C++ declarations, it does not provide
 4354  a complete C/C++ parser implementation. Most of these limitations
 4355  pertain to very complicated type declarations and certain advanced C++
 4356  features. Specifically, the following features are not currently
 4357  supported:</p>
 4358 <ul>
 4359 <li>
 4360 <p> Non-conventional type declarations. For example, SWIG does not
 4361  support declarations such as the following (even though this is legal
 4362  C):</p>
 4363 <div class="code">
 4364 <pre>
 4365 /* Non-conventional placement of storage specifier (extern) */
 4366 const int extern Number;
 4368 /* Extra declarator grouping */
 4369 Matrix (foo);    // A global variable
 4371 /* Extra declarator grouping in parameters */
 4372 void bar(Spam (Grok)(Doh));
 4374 </pre>
 4375 </div>
 4376 <p> In practice, few (if any) C programmers actually write code like
 4377  this since this style is never featured in programming books. However,
 4378  if you're feeling particularly obfuscated, you can certainly break SWIG
 4379  (although why would you want to?).</p>
 4380 </li>
 4381 <li>
 4382 <p> Running SWIG on C++ source files (the code in a .C, .cpp or .cxx
 4383  file) is not recommended. The usual approach is to feed SWIG header
 4384  files for parsing C++ definitions and declarations. The main reason is
 4385  if SWIG parses a scoped definition or declaration (as is normal for C++
 4386  source files), it is ignored, unless a declaration for the symbol was
 4387  parsed earlier. For example</p>
 4388 <div class="code">
 4389 <pre>
 4390 /* bar not wrapped unless foo has been defined and 
 4391    the declaration of bar within foo has already been parsed */
 4392 int foo::bar(int) {
 4393   ... whatever ...
 4394 }
 4395 </pre>
 4396 </div></li>
 4397 <li>
 4398 <p> Certain advanced features of C++ such as nested classes are not yet
 4399  fully supported. Please see the C++ <a href="#SWIGPlus_nested_classes">
 4400 Nested classes</a> section for more information.</p>
 4401 </li>
 4402 </ul>
 4403 <p> In the event of a parsing error, conditional compilation can be used
 4404  to skip offending code. For example:</p>
 4405 <div class="code">
 4406 <pre>
 4407 #ifndef SWIG
 4408 ... some bad declarations ...
 4409 #endif
 4410 </pre>
 4411 </div>
 4412 <p> Alternatively, you can just delete the offending code from the
 4413  interface file.</p>
 4414 <p> One of the reasons why SWIG does not provide a full C++ parser
 4415  implementation is that it has been designed to work with incomplete
 4416  specifications and to be very permissive in its handling of C/C++
 4417  datatypes (e.g., SWIG can generate interfaces even when there are
 4418  missing class declarations or opaque datatypes). Unfortunately, this
 4419  approach makes it extremely difficult to implement certain parts of a
 4420  C/C++ parser as most compilers use type information to assist in the
 4421  parsing of more complex declarations (for the truly curious, the
 4422  primary complication in the implementation is that the SWIG parser does
 4423  not utilize a separate<em> typedef-name</em> terminal symbol as
 4424  described on p. 234 of K&amp;R).</p>
 4425 <h2><a name="SWIG_nn9">5.2 Wrapping Simple C Declarations</a></h2>
 4426 <p> SWIG wraps simple C declarations by creating an interface that
 4427  closely matches the way in which the declarations would be used in a C
 4428  program. For example, consider the following interface file:</p>
 4429 <div class="code">
 4430 <pre>
 4431 %module example
 4433 %inline %{
 4434 extern double sin(double x);
 4435 extern int strcmp(const char *, const char *);
 4436 extern int Foo;
 4437 %}
 4438 #define STATUS 50
 4439 #define VERSION &quot;1.1&quot;
 4440 </pre>
 4441 </div>
 4442 <p> In this file, there are two functions <tt>sin()</tt> and <tt>
 4443 strcmp()</tt>, a global variable <tt>Foo</tt>, and two constants <tt>
 4444 STATUS</tt> and <tt>VERSION</tt>. When SWIG creates an extension module,
 4445  these declarations are accessible as scripting language functions,
 4446  variables, and constants respectively. For example, in Tcl:</p>
 4447 <div class="targetlang">
 4448 <pre>
 4449 % sin 3
 4450 5.2335956
 4451 % strcmp Dave Mike
 4452 -1
 4453 % puts $Foo
 4454 42
 4455 % puts $STATUS
 4456 50
 4457 % puts $VERSION
 4458 1.1
 4459 </pre>
 4460 </div>
 4461 <p> Or in Python:</p>
 4462 <div class="targetlang">
 4463 <pre>
 4464 &gt;&gt;&gt; example.sin(3)
 4465 5.2335956
 4466 &gt;&gt;&gt; example.strcmp('Dave', 'Mike')
 4467 -1
 4468 &gt;&gt;&gt; print example.cvar.Foo
 4469 42
 4470 &gt;&gt;&gt; print example.STATUS
 4471 50
 4472 &gt;&gt;&gt; print example.VERSION
 4473 1.1
 4474 </pre>
 4475 </div>
 4476 <p> Whenever possible, SWIG creates an interface that closely matches
 4477  the underlying C/C++ code. However, due to subtle differences between
 4478  languages, run-time environments, and semantics, it is not always
 4479  possible to do so. The next few sections describe various aspects of
 4480  this mapping.</p>
 4481 <h3><a name="SWIG_nn10">5.2.1 Basic Type Handling</a></h3>
 4482 <p> In order to build an interface, SWIG has to convert C/C++ datatypes
 4483  to equivalent types in the target language. Generally, scripting
 4484  languages provide a more limited set of primitive types than C.
 4485  Therefore, this conversion process involves a certain amount of type
 4486  coercion.</p>
 4487 <p> Most scripting languages provide a single integer type that is
 4488  implemented using the <tt>int</tt> or <tt>long</tt> datatype in C. The
 4489  following list shows all of the C datatypes that SWIG will convert to
 4490  and from integers in the target language:</p>
 4491 <div class="code">
 4492 <pre>
 4493 int
 4494 short
 4495 long
 4496 unsigned
 4497 signed
 4498 unsigned short
 4499 unsigned long
 4500 unsigned char
 4501 signed char
 4502 bool
 4503 </pre>
 4504 </div>
 4505 <p> When an integral value is converted from C, a cast is used to
 4506  convert it to the representation in the target language. Thus, a 16 bit
 4507  short in C may be promoted to a 32 bit integer. When integers are
 4508  converted in the other direction, the value is cast back into the
 4509  original C type. If the value is too large to fit, it is silently
 4510  truncated.
 4511 <!-- Dave: Maybe we should fix this -->
 4512 </p>
 4513 <p> <tt>unsigned char</tt> and <tt>signed char</tt> are special cases
 4514  that are handled as small 8-bit integers. Normally, the <tt>char</tt>
 4515  datatype is mapped as a one-character ASCII string.</p>
 4516 <p> The <tt>bool</tt> datatype is cast to and from an integer value of 0
 4517  and 1 unless the target language provides a special boolean type.</p>
 4518 <p> Some care is required when working with large integer values. Most
 4519  scripting languages use 32-bit integers so mapping a 64-bit long
 4520  integer may lead to truncation errors. Similar problems may arise with
 4521  32 bit unsigned integers (which may appear as large negative numbers).
 4522  As a rule of thumb, the <tt>int</tt> datatype and all variations of <tt>
 4523 char</tt> and <tt>short</tt> datatypes are safe to use. For <tt>unsigned
 4524  int</tt> and <tt>long</tt> datatypes, you will need to carefully check
 4525  the correct operation of your program after it has been wrapped with
 4526  SWIG.</p>
 4527 <p> Although the SWIG parser supports the <tt>long long</tt> datatype,
 4528  not all language modules support it. This is because <tt>long long</tt>
 4529  usually exceeds the integer precision available in the target language.
 4530  In certain modules such as Tcl and Perl5, <tt>long long</tt> integers
 4531  are encoded as strings. This allows the full range of these numbers to
 4532  be represented. However, it does not allow <tt>long long</tt> values to
 4533  be used in arithmetic expressions. It should also be noted that
 4534  although <tt>long long</tt> is part of the ISO C99 standard, it is not
 4535  universally supported by all C compilers. Make sure you are using a
 4536  compiler that supports <tt>long long</tt> before trying to use this
 4537  type with SWIG.</p>
 4538 <p> SWIG recognizes the following floating point types :</p>
 4539 <div class="code">
 4540 <pre>
 4541 float
 4542 double
 4543 </pre>
 4544 </div>
 4545 <p> Floating point numbers are mapped to and from the natural
 4546  representation of floats in the target language. This is almost always
 4547  a C <tt>double</tt>. The rarely used datatype of <tt>long double</tt>
 4548  is not supported by SWIG.</p>
 4549 <p> The <tt>char</tt> datatype is mapped into a NULL terminated ASCII
 4550  string with a single character. When used in a scripting language it
 4551  shows up as a tiny string containing the character value. When
 4552  converting the value back into C, SWIG takes a character string from
 4553  the scripting language and strips off the first character as the char
 4554  value. Thus if the value &quot;foo&quot; is assigned to a <tt>char</tt> datatype,
 4555  it gets the value `f'.</p>
 4556 <p> The <tt>char *</tt> datatype is handled as a NULL-terminated ASCII
 4557  string. SWIG maps this into a 8-bit character string in the target
 4558  scripting language. SWIG converts character strings in the target
 4559  language to NULL terminated strings before passing them into C/C++. The
 4560  default handling of these strings does not allow them to have embedded
 4561  NULL bytes. Therefore, the <tt>char *</tt> datatype is not generally
 4562  suitable for passing binary data. However, it is possible to change
 4563  this behavior by defining a SWIG typemap. See the chapter on <a href="#Typemaps">
 4564 Typemaps</a> for details about this.</p>
 4565 <p> At this time, SWIG provides limited support for Unicode and
 4566  wide-character strings (the C <tt>wchar_t</tt> type). Some languages
 4567  provide typemaps for wchar_t, but bear in mind these might not be
 4568  portable across different operating systems. This is a delicate topic
 4569  that is poorly understood by many programmers and not implemented in a
 4570  consistent manner across languages. For those scripting languages that
 4571  provide Unicode support, Unicode strings are often available in an
 4572  8-bit representation such as UTF-8 that can be mapped to the <tt>char *</tt>
 4573  type (in which case the SWIG interface will probably work). If the
 4574  program you are wrapping uses Unicode, there is no guarantee that
 4575  Unicode characters in the target language will use the same internal
 4576  representation (e.g., UCS-2 vs. UCS-4). You may need to write some
 4577  special conversion functions.</p>
 4578 <h3><a name="SWIG_nn11">5.2.2 Global Variables</a></h3>
 4579 <p> Whenever possible, SWIG maps C/C++ global variables into scripting
 4580  language variables. For example,</p>
 4581 <div class="code">
 4582 <pre>
 4583 %module example
 4584 double foo;
 4586 </pre>
 4587 </div>
 4588 <p> results in a scripting language variable like this:</p>
 4589 <div class="code">
 4590 <pre>
 4591 # Tcl
 4592 set foo [3.5]                   ;# Set foo to 3.5
 4593 puts $foo                       ;# Print the value of foo
 4595 # Python
 4596 cvar.foo = 3.5                  # Set foo to 3.5
 4597 print cvar.foo                  # Print value of foo
 4599 # Perl
 4600 $foo = 3.5;                     # Set foo to 3.5
 4601 print $foo, &quot;\n&quot;;               # Print value of foo
 4603 # Ruby
 4604 Module.foo = 3.5               # Set foo to 3.5
 4605 print Module.foo, &quot;\n&quot;         # Print value of foo
 4606 </pre>
 4607 </div>
 4608 <p> Whenever the scripting language variable is used, the underlying C
 4609  global variable is accessed. Although SWIG makes every attempt to make
 4610  global variables work like scripting language variables, it is not
 4611  always possible to do so. For instance, in Python, all global variables
 4612  must be accessed through a special variable object known as <tt>cvar</tt>
 4613  (shown above). In Ruby, variables are accessed as attributes of the
 4614  module. Other languages may convert variables to a pair of accessor
 4615  functions. For example, the Java module generates a pair of functions <tt>
 4616 double get_foo()</tt> and <tt>set_foo(double val)</tt> that are used to
 4617  manipulate the value.</p>
 4618 <p> Finally, if a global variable has been declared as <tt>const</tt>,
 4619  it only supports read-only access. Note: this behavior is new to
 4620  SWIG-1.3. Earlier versions of SWIG incorrectly handled <tt>const</tt>
 4621  and created constants instead.</p>
 4622 <h3><a name="SWIG_nn12">5.2.3 Constants</a></h3>
 4623 <p> Constants can be created using <tt>#define</tt>, enumerations, or a
 4624  special <tt>%constant</tt> directive. The following interface file
 4625  shows a few valid constant declarations :</p>
 4626 <div class="code">
 4627 <pre>
 4628 #define I_CONST       5               // An integer constant
 4629 #define PI            3.14159         // A Floating point constant
 4630 #define S_CONST       &quot;hello world&quot;   // A string constant
 4631 #define NEWLINE       '\n'            // Character constant
 4633 enum boolean {NO=0, YES=1};
 4634 enum months {JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
 4635              SEP, OCT, NOV, DEC};
 4636 %constant double BLAH = 42.37;
 4637 #define PI_4 PI/4
 4638 #define FLAGS 0x04 | 0x08 | 0x40
 4640 </pre>
 4641 </div>
 4642 <p> In <tt>#define</tt> declarations, the type of a constant is inferred
 4643  by syntax. For example, a number with a decimal point is assumed to be
 4644  floating point. In addition, SWIG must be able to fully resolve all of
 4645  the symbols used in a <tt>#define</tt> in order for a constant to
 4646  actually be created. This restriction is necessary because <tt>#define</tt>
 4647  is also used to define preprocessor macros that are definitely not
 4648  meant to be part of the scripting language interface. For example:</p>
 4649 <div class="code">
 4650 <pre>
 4651 #define EXTERN extern
 4653 EXTERN void foo();
 4654 </pre>
 4655 </div>
 4656 <p> In this case, you probably don't want to create a constant called <tt>
 4657 EXTERN</tt> (what would the value be?). In general, SWIG will not create
 4658  constants for macros unless the value can be completely determined by
 4659  the preprocessor. For instance, in the above example, the declaration</p>
 4660 <div class="code">
 4661 <pre>
 4662 #define PI_4  PI/4
 4663 </pre>
 4664 </div>
 4665 <p> defines a constant because <tt>PI</tt> was already defined as a
 4666  constant and the value is known. However, for the same conservative
 4667  reasons even a constant with a simple cast will be ignored, such as</p>
 4668 <div class="code">
 4669 <pre>
 4670 #define F_CONST (double) 5            // A floating point constant with cast
 4671 </pre>
 4672 </div>
 4673 <p> This logic can lead to false attempts at converting <tt>#define</tt>
 4674  into <tt>%constant</tt> though. For example the following case does not
 4675  have any undefined symbols within the macro:</p>
 4676 <div class="code">
 4677 <pre>
 4678 // For indicating pure virtual functions such as: virtual void f() PURE;
 4679 #define PURE = 0
 4680 </pre>
 4681 </div>
 4682 <p> A warning is issued:</p>
 4683 <div class="shell">
 4684 <pre>
 4685 pure.h:1: Warning 305: Bad constant value (ignored).
 4686 </pre>
 4687 </div>
 4688 <p> In such cases simply ignore the warning or suppress it using the
 4689  normal warning suppression techniques.</p>
 4690 <p> The use of constant expressions is allowed, but SWIG does not
 4691  evaluate them. Rather, it passes them through to the output file and
 4692  lets the C compiler perform the final evaluation (SWIG does perform a
 4693  limited form of type-checking however).</p>
 4694 <p> For enumerations, it is critical that the original enum definition
 4695  be included somewhere in the interface file (either in a header file or
 4696  in the <tt>%{ %}</tt> block). SWIG only translates the enumeration into
 4697  code needed to add the constants to a scripting language. It needs the
 4698  original enumeration declaration in order to get the correct enum
 4699  values as assigned by the C compiler.</p>
 4700 <p> The <tt>%constant</tt> directive is used to more precisely create
 4701  constants corresponding to different C datatypes. Although it is not
 4702  usually needed for simple values, it is more useful when working with
 4703  pointers and other more complex datatypes. Typically, <tt>%constant</tt>
 4704  is only used when you want to add constants to the scripting language
 4705  interface that are not defined in the original header file.</p>
 4706 <h3><a name="SWIG_nn13">5.2.4 A brief word about const</a></h3>
 4707 <p> A common confusion with C programming is the semantic meaning of the
 4708  <tt>const</tt> qualifier in declarations--especially when it is mixed
 4709  with pointers and other type modifiers. In fact, previous versions of
 4710  SWIG handled <tt>const</tt> incorrectly--a situation that SWIG-1.3.7
 4711  and newer releases have fixed.</p>
 4712 <p> Starting with SWIG-1.3, all variable declarations, regardless of any
 4713  use of <tt>const</tt>, are wrapped as global variables. If a
 4714  declaration happens to be declared as <tt>const</tt>, it is wrapped as
 4715  a read-only variable. To tell if a variable is <tt>const</tt> or not,
 4716  you need to look at the right-most occurrence of the <tt>const</tt>
 4717  qualifier (that appears before the variable name). If the right-most <tt>
 4718 const</tt> occurs after all other type modifiers (such as pointers),
 4719  then the variable is <tt>const</tt>. Otherwise, it is not.</p>
 4720 <p> Here are some examples of <tt>const</tt> declarations.</p>
 4721 <div class="code">
 4722 <pre>
 4723 const char a;           // A constant character
 4724 char const b;           // A constant character (the same)
 4725 char *const c;          // A constant pointer to a character
 4726 const char *const d;    // A constant pointer to a constant character
 4727 </pre>
 4728 </div>
 4729 <p> Here is an example of a declaration that is not <tt>const</tt>:</p>
 4730 <div class="code">
 4731 <pre>
 4732 const char *e;          // A pointer to a constant character.  The pointer
 4733                         // may be modified.
 4734 </pre>
 4735 </div>
 4736 <p> In this case, the pointer <tt>e</tt> can change---it's only the
 4737  value being pointed to that is read-only.</p>
 4738 <p> Please note that for const parameters or return types used in a
 4739  function, SWIG pretty much ignores the fact that these are const, see
 4740  the section on <a href="#SWIGPlus_const">const-correctness</a> for more
 4741  information.</p>
 4742 <p><b> Compatibility Note:</b> One reason for changing SWIG to handle <tt>
 4743 const</tt> declarations as read-only variables is that there are many
 4744  situations where the value of a <tt>const</tt> variable might change.
 4745  For example, a library might export a symbol as <tt>const</tt> in its
 4746  public API to discourage modification, but still allow the value to
 4747  change through some other kind of internal mechanism. Furthermore,
 4748  programmers often overlook the fact that with a constant declaration
 4749  like <tt>char *const</tt>, the underlying data being pointed to can be
 4750  modified--it's only the pointer itself that is constant. In an embedded
 4751  system, a <tt>const</tt> declaration might refer to a read-only memory
 4752  address such as the location of a memory-mapped I/O device port (where
 4753  the value changes, but writing to the port is not supported by the
 4754  hardware). Rather than trying to build a bunch of special cases into
 4755  the <tt>const</tt> qualifier, the new interpretation of <tt>const</tt>
 4756  as &quot;read-only&quot; is simple and exactly matches the actual semantics of <tt>
 4757 const</tt> in C/C++. If you really want to create a constant as in older
 4758  versions of SWIG, use the <tt>%constant</tt> directive instead. For
 4759  example:</p>
 4760 <div class="code">
 4761 <pre>
 4762 %constant double PI = 3.14159;
 4763 </pre>
 4764 </div>
 4765 <p> or</p>
 4766 <div class="code">
 4767 <pre>
 4768 #ifdef SWIG
 4769 #define const %constant
 4770 #endif
 4771 const double foo = 3.4;
 4772 const double bar = 23.4;
 4773 const int    spam = 42;
 4774 #ifdef SWIG
 4775 #undef const
 4776 #endif
 4777 ...
 4779 </pre>
 4780 </div>
 4781 <h3><a name="SWIG_nn14">5.2.5 A cautionary tale of char *</a></h3>
 4782 <p> Before going any further, there is one bit of caution involving <tt>
 4783 char *</tt> that must now be mentioned. When strings are passed from a
 4784  scripting language to a C <tt>char *</tt>, the pointer usually points
 4785  to string data stored inside the interpreter. It is almost always a
 4786  really bad idea to modify this data. Furthermore, some languages may
 4787  explicitly disallow it. For instance, in Python, strings are supposed
 4788  to be immutable. If you violate this, you will probably receive a vast
 4789  amount of wrath when you unleash your module on the world.</p>
 4790 <p> The primary source of problems are functions that might modify
 4791  string data in place. A classic example would be a function like this:</p>
 4792 <div class="code">
 4793 <pre>
 4794 char *strcat(char *s, const char *t)
 4795 </pre>
 4796 </div>
 4797 <p> Although SWIG will certainly generate a wrapper for this, its
 4798  behavior will be undefined. In fact, it will probably cause your
 4799  application to crash with a segmentation fault or other memory related
 4800  problem. This is because <tt>s</tt> refers to some internal data in the
 4801  target language---data that you shouldn't be touching.</p>
 4802 <p> The bottom line: don't rely on <tt>char *</tt> for anything other
 4803  than read-only input values. However, it must be noted that you could
 4804  change the behavior of SWIG using <a href="#Typemaps">typemaps</a>.</p>
 4805 <h2><a name="SWIG_nn15">5.3 Pointers and complex objects</a></h2>
 4806 <p> Most C programs manipulate arrays, structures, and other types of
 4807  objects. This section discusses the handling of these datatypes.</p>
 4808 <h3><a name="SWIG_nn16">5.3.1 Simple pointers</a></h3>
 4809 <p> Pointers to primitive C datatypes such as</p>
 4810 <div class="code">
 4811 <pre>
 4812 int *
 4813 double ***
 4814 char **
 4815 </pre>
 4816 </div>
 4817 <p> are fully supported by SWIG. Rather than trying to convert the data
 4818  being pointed to into a scripting representation, SWIG simply encodes
 4819  the pointer itself into a representation that contains the actual value
 4820  of the pointer and a type-tag. Thus, the SWIG representation of the
 4821  above pointers (in Tcl), might look like this:</p>
 4822 <div class="targetlang">
 4823 <pre>
 4824 _10081012_p_int
 4825 _1008e124_ppp_double
 4826 _f8ac_pp_char
 4827 </pre>
 4828 </div>
 4829 <p> A NULL pointer is represented by the string &quot;NULL&quot; or the value 0
 4830  encoded with type information.</p>
 4831 <p> All pointers are treated as opaque objects by SWIG. Thus, a pointer
 4832  may be returned by a function and passed around to other C functions as
 4833  needed. For all practical purposes, the scripting language interface
 4834  works in exactly the same way as you would use the pointer in a C
 4835  program. The only difference is that there is no mechanism for
 4836  dereferencing the pointer since this would require the target language
 4837  to understand the memory layout of the underlying object.</p>
 4838 <p> The scripting language representation of a pointer value should
 4839  never be manipulated directly. Even though the values shown look like
 4840  hexadecimal addresses, the numbers used may differ from the actual
 4841  machine address (e.g., on little-endian machines, the digits may appear
 4842  in reverse order). Furthermore, SWIG does not normally map pointers
 4843  into high-level objects such as associative arrays or lists (for
 4844  example, converting an <tt>int *</tt> into an list of integers). There
 4845  are several reasons why SWIG does not do this:</p>
 4846 <ul>
 4847 <li>There is not enough information in a C declaration to properly map
 4848  pointers into higher level constructs. For example, an <tt>int *</tt>
 4849  may indeed be an array of integers, but if it contains ten million
 4850  elements, converting it into a list object is probably a bad idea.</li>
 4851 <li>The underlying semantics associated with a pointer is not known by
 4852  SWIG. For instance, an <tt>int *</tt> might not be an array at
 4853  all--perhaps it is an output value!</li>
 4854 <li>By handling all pointers in a consistent manner, the implementation
 4855  of SWIG is greatly simplified and less prone to error.</li>
 4856 </ul>
 4857 <h3><a name="SWIG_nn17">5.3.2 Run time pointer type checking</a></h3>
 4858 <p> By allowing pointers to be manipulated from a scripting language,
 4859  extension modules effectively bypass compile-time type checking in the
 4860  C/C++ compiler. To prevent errors, a type signature is encoded into all
 4861  pointer values and is used to perform run-time type checking. This
 4862  type-checking process is an integral part of SWIG and can not be
 4863  disabled or modified without using typemaps (described in later
 4864  chapters).</p>
 4865 <p> Like C, <tt>void *</tt> matches any kind of pointer. Furthermore, <tt>
 4866 NULL</tt> pointers can be passed to any function that expects to receive
 4867  a pointer. Although this has the potential to cause a crash, <tt>NULL</tt>
 4868  pointers are also sometimes used as sentinel values or to denote a
 4869  missing/empty value. Therefore, SWIG leaves NULL pointer checking up to
 4870  the application.</p>
 4871 <h3><a name="SWIG_nn18">5.3.3 Derived types, structs, and classes</a></h3>
 4872 <p> For everything else (structs, classes, arrays, etc...) SWIG applies
 4873  a very simple rule :</p>
 4874 <center><b> Everything else is a pointer</b></center>
 4875 <p> In other words, SWIG manipulates everything else by reference. This
 4876  model makes sense because most C/C++ programs make heavy use of
 4877  pointers and SWIG can use the type-checked pointer mechanism already
 4878  present for handling pointers to basic datatypes.</p>
 4879 <p> Although this probably sounds complicated, it's really quite simple.
 4880  Suppose you have an interface file like this :</p>
 4881 <div class="code">
 4882 <pre>
 4883 %module fileio
 4884 FILE *fopen(char *, char *);
 4885 int fclose(FILE *);
 4886 unsigned fread(void *ptr, unsigned size, unsigned nobj, FILE *);
 4887 unsigned fwrite(void *ptr, unsigned size, unsigned nobj, FILE *);
 4888 void *malloc(int nbytes);
 4889 void free(void *);
 4891 </pre>
 4892 </div>
 4893 <p> In this file, SWIG doesn't know what a <tt>FILE</tt> is, but since
 4894  it's used as a pointer, so it doesn't really matter what it is. If you
 4895  wrapped this module into Python, you can use the functions just like
 4896  you expect :</p>
 4897 <div class="targetlang">
 4898 <pre>
 4899 # Copy a file 
 4900 def filecopy(source, target):
 4901     f1 = fopen(source, &quot;r&quot;)
 4902     f2 = fopen(target, &quot;w&quot;)
 4903     buffer = malloc(8192)
 4904     nbytes = fread(buffer, 8192, 1, f1)
 4905     while (nbytes &gt; 0):
 4906         fwrite(buffer, 8192, 1, f2)
 4907             nbytes = fread(buffer, 8192, 1, f1)
 4908     free(buffer)
 4909 </pre>
 4910 </div>
 4911 <p> In this case <tt>f1</tt>, <tt>f2</tt>, and <tt>buffer</tt> are all
 4912  opaque objects containing C pointers. It doesn't matter what value they
 4913  contain--our program works just fine without this knowledge.</p>
 4914 <h3><a name="SWIG_nn19">5.3.4 Undefined datatypes</a></h3>
 4915 <p> When SWIG encounters an undeclared datatype, it automatically
 4916  assumes that it is a structure or class. For example, suppose the
 4917  following function appeared in a SWIG input file:</p>
 4918 <div class="code">
 4919 <pre>
 4920 void matrix_multiply(Matrix *a, Matrix *b, Matrix *c);
 4921 </pre>
 4922 </div>
 4923 <p> SWIG has no idea what a &quot;<tt>Matrix</tt>&quot; is. However, it is
 4924  obviously a pointer to something so SWIG generates a wrapper using its
 4925  generic pointer handling code.</p>
 4926 <p> Unlike C or C++, SWIG does not actually care whether <tt>Matrix</tt>
 4927  has been previously defined in the interface file or not. This allows
 4928  SWIG to generate interfaces from only partial or limited information.
 4929  In some cases, you may not care what a <tt>Matrix</tt> really is as
 4930  long as you can pass an opaque reference to one around in the scripting
 4931  language interface.</p>
 4932 <p> An important detail to mention is that SWIG will gladly generate
 4933  wrappers for an interface when there are unspecified type names.
 4934  However,<b> all unspecified types are internally handled as pointers to
 4935  structures or classes!</b> For example, consider the following
 4936  declaration:</p>
 4937 <div class="code">
 4938 <pre>
 4939 void foo(size_t num);
 4940 </pre>
 4941 </div>
 4942 <p> If <tt>size_t</tt> is undeclared, SWIG generates wrappers that
 4943  expect to receive a type of <tt>size_t *</tt> (this mapping is
 4944  described shortly). As a result, the scripting interface might behave
 4945  strangely. For example:</p>
 4946 <div class="code">
 4947 <pre>
 4948 foo(40);
 4949 TypeError: expected a _p_size_t.
 4950 </pre>
 4951 </div>
 4952 <p> The only way to fix this problem is to make sure you properly
 4953  declare type names using <tt>typedef</tt>.</p>
 4955 <!-- We might want to add an error reporting flag to swig -->
 4956 <h3><a name="SWIG_nn20">5.3.5 Typedef</a></h3>
 4957 <p> Like C, <tt>typedef</tt> can be used to define new type names in
 4958  SWIG. For example:</p>
 4959 <div class="code">
 4960 <pre>
 4961 typedef unsigned int size_t;
 4962 </pre>
 4963 </div>
 4964 <p> <tt>typedef</tt> definitions appearing in a SWIG interface are not
 4965  propagated to the generated wrapper code. Therefore, they either need
 4966  to be defined in an included header file or placed in the declarations
 4967  section like this:</p>
 4968 <div class="code">
 4969 <pre>
 4970 %{
 4971 /* Include in the generated wrapper file */
 4972 typedef unsigned int size_t;
 4973 %}
 4974 /* Tell SWIG about it */
 4975 typedef unsigned int size_t;
 4976 </pre>
 4977 </div>
 4978 <p> or</p>
 4979 <div class="code">
 4980 <pre>
 4981 %inline %{
 4982 typedef unsigned int size_t;
 4983 %}
 4984 </pre>
 4985 </div>
 4986 <p> In certain cases, you might be able to include other header files to
 4987  collect type information. For example:</p>
 4988 <div class="code">
 4989 <pre>
 4990 %module example
 4991 %import &quot;sys/types.h&quot;
 4992 </pre>
 4993 </div>
 4994 <p> In this case, you might run SWIG as follows:</p>
 4995 <div class="shell">
 4996 <pre>
 4997 $ swig -I/usr/include -includeall example.i
 4998 </pre>
 4999 </div>
 5000 <p> It should be noted that your mileage will vary greatly here. System
 5001  headers are notoriously complicated and may rely upon a variety of
 5002  non-standard C coding extensions (e.g., such as special directives to
 5003  GCC). Unless you exactly specify the right include directories and
 5004  preprocessor symbols, this may not work correctly (you will have to
 5005  experiment).</p>
 5006 <p> SWIG tracks <tt>typedef</tt> declarations and uses this information
 5007  for run-time type checking. For instance, if you use the above <tt>
 5008 typedef</tt> and had the following function declaration:</p>
 5009 <div class="code">
 5010 <pre>
 5011 void foo(unsigned int *ptr);
 5012 </pre>
 5013 </div>
 5014 <p> The corresponding wrapper function will accept arguments of type <tt>
 5015 unsigned int *</tt> or <tt>size_t *</tt>.</p>
 5016 <h2><a name="SWIG_nn21">5.4 Other Practicalities</a></h2>
 5017 <p> So far, this chapter has presented almost everything you need to
 5018  know to use SWIG for simple interfaces. However, some C programs use
 5019  idioms that are somewhat more difficult to map to a scripting language
 5020  interface. This section describes some of these issues.</p>
 5021 <h3><a name="SWIG_nn22">5.4.1 Passing structures by value</a></h3>
 5022 <p> Sometimes a C function takes structure parameters that are passed by
 5023  value. For example, consider the following function:</p>
 5024 <div class="code">
 5025 <pre>
 5026 double dot_product(Vector a, Vector b);
 5027 </pre>
 5028 </div>
 5029 <p> To deal with this, SWIG transforms the function to use pointers by
 5030  creating a wrapper equivalent to the following:</p>
 5031 <div class="code">
 5032 <pre>
 5033 double wrap_dot_product(Vector *a, Vector *b) {
 5034   Vector x = *a;
 5035   Vector y = *b;
 5036   return dot_product(x, y);
 5037 }
 5038 </pre>
 5039 </div>
 5040 <p> In the target language, the <tt>dot_product()</tt> function now
 5041  accepts pointers to Vectors instead of Vectors. For the most part, this
 5042  transformation is transparent so you might not notice.</p>
 5043 <h3><a name="SWIG_nn23">5.4.2 Return by value</a></h3>
 5044 <p> C functions that return structures or classes datatypes by value are
 5045  more difficult to handle. Consider the following function:</p>
 5046 <div class="code">
 5047 <pre>
 5048 Vector cross_product(Vector v1, Vector v2);
 5049 </pre>
 5050 </div>
 5051 <p> This function wants to return <tt>Vector</tt>, but SWIG only really
 5052  supports pointers. As a result, SWIG creates a wrapper like this:</p>
 5053 <div class="code">
 5054 <pre>
 5055 Vector *wrap_cross_product(Vector *v1, Vector *v2) {
 5056   Vector x = *v1;
 5057   Vector y = *v2;
 5058   Vector *result;
 5059   result = (Vector *) malloc(sizeof(Vector));
 5060   *(result) = cross(x, y);
 5061   return result;
 5062 }
 5063 </pre>
 5064 </div>
 5065 <p> or if SWIG was run with the <tt>-c++</tt> option:</p>
 5066 <div class="code">
 5067 <pre>
 5068 Vector *wrap_cross(Vector *v1, Vector *v2) {
 5069   Vector x = *v1;
 5070   Vector y = *v2;
 5071   Vector *result = new Vector(cross(x, y)); // Uses default copy constructor
 5072   return result;
 5073 }
 5074 </pre>
 5075 </div>
 5076 <p> In both cases, SWIG allocates a new object and returns a reference
 5077  to it. It is up to the user to delete the returned object when it is no
 5078  longer in use. Clearly, this will leak memory if you are unaware of the
 5079  implicit memory allocation and don't take steps to free the result.
 5080  That said, it should be noted that some language modules can now
 5081  automatically track newly created objects and reclaim memory for you.
 5082  Consult the documentation for each language module for more details.</p>
 5083 <p> It should also be noted that the handling of pass/return by value in
 5084  C++ has some special cases. For example, the above code fragments don't
 5085  work correctly if <tt>Vector</tt> doesn't define a default constructor.
 5086  The section on SWIG and C++ has more information about this case.</p>
 5087 <h3><a name="SWIG_nn24">5.4.3 Linking to structure variables</a></h3>
 5088 <p> When global variables or class members involving structures are
 5089  encountered, SWIG handles them as pointers. For example, a global
 5090  variable like this</p>
 5091 <div class="code">
 5092 <pre>
 5093 Vector unit_i;
 5094 </pre>
 5095 </div>
 5096 <p> gets mapped to an underlying pair of set/get functions like this :</p>
 5097 <div class="code">
 5098 <pre>
 5099 Vector *unit_i_get() {
 5100   return &amp;unit_i;
 5101 }
 5102 void unit_i_set(Vector *value) {
 5103   unit_i = *value;
 5104 }
 5105 </pre>
 5106 </div>
 5107 <p> Again some caution is in order. A global variable created in this
 5108  manner will show up as a pointer in the target scripting language. It
 5109  would be an extremely bad idea to free or destroy such a pointer. Also,
 5110  C++ classes must supply a properly defined copy constructor in order
 5111  for assignment to work correctly.</p>
 5112 <h3><a name="SWIG_nn25">5.4.4 Linking to char *</a></h3>
 5113 <p> When a global variable of type <tt>char *</tt> appears, SWIG uses <tt>
 5114 malloc()</tt> or <tt>new</tt> to allocate memory for the new value.
 5115  Specifically, if you have a variable like this</p>
 5116 <div class="code">
 5117 <pre>
 5118 char *foo;
 5119 </pre>
 5120 </div>
 5121 <p> SWIG generates the following code:</p>
 5122 <div class="code">
 5123 <pre>
 5124 /* C mode */
 5125 void foo_set(char *value) {
 5126   free(foo);
 5127   foo = (char *) malloc(strlen(value)+1);
 5128   strcpy(foo, value);
 5129 }
 5131 /* C++ mode.  When -c++ option is used */
 5132 void foo_set(char *value) {
 5133   delete [] foo;
 5134   foo = new char[strlen(value)+1];
 5135   strcpy(foo, value);
 5136 }
 5137 </pre>
 5138 </div>
 5139 <p> If this is not the behavior that you want, consider making the
 5140  variable read-only using the <tt>%immutable</tt> directive.
 5141  Alternatively, you might write a short assist-function to set the value
 5142  exactly like you want. For example:</p>
 5143 <div class="code">
 5144 <pre>
 5145 %inline %{
 5146   void set_foo(char *value) {
 5147     strncpy(foo, value, 50);
 5148   }
 5149 %}
 5150 </pre>
 5151 </div>
 5152 <p> Note: If you write an assist function like this, you will have to
 5153  call it as a function from the target scripting language (it does not
 5154  work like a variable). For example, in Python you will have to write:</p>
 5155 <div class="targetlang">
 5156 <pre>
 5157 &gt;&gt;&gt; set_foo(&quot;Hello World&quot;)
 5158 </pre>
 5159 </div>
 5160 <p> A common mistake with <tt>char *</tt> variables is to link to a
 5161  variable declared like this:</p>
 5162 <div class="code">
 5163 <pre>
 5164 char *VERSION = &quot;1.0&quot;;
 5165 </pre>
 5166 </div>
 5167 <p> In this case, the variable will be readable, but any attempt to
 5168  change the value results in a segmentation or general protection fault.
 5169  This is due to the fact that SWIG is trying to release the old value
 5170  using <tt>free</tt> or <tt>delete</tt> when the string literal value
 5171  currently assigned to the variable wasn't allocated using <tt>malloc()</tt>
 5172  or <tt>new</tt>. To fix this behavior, you can either mark the variable
 5173  as read-only, write a typemap (as described in Chapter 6), or write a
 5174  special set function as shown. Another alternative is to declare the
 5175  variable as an array:</p>
 5176 <div class="code">
 5177 <pre>
 5178 char VERSION[64] = &quot;1.0&quot;;
 5179 </pre>
 5180 </div>
 5181 <p> When variables of type <tt>const char *</tt> are declared, SWIG
 5182  still generates functions for setting and getting the value. However,
 5183  the default behavior does<em> not</em> release the previous contents
 5184  (resulting in a possible memory leak). In fact, you may get a warning
 5185  message such as this when wrapping such a variable:</p>
 5186 <div class="shell">
 5187 <pre>
 5188 example.i:20. Typemap warning. Setting const char * variable may leak memory
 5189 </pre>
 5190 </div>
 5191 <p> The reason for this behavior is that <tt>const char *</tt> variables
 5192  are often used to point to string literals. For example:</p>
 5193 <div class="code">
 5194 <pre>
 5195 const char *foo = &quot;Hello World\n&quot;;
 5196 </pre>
 5197 </div>
 5198 <p> Therefore, it's a really bad idea to call <tt>free()</tt> on such a
 5199  pointer. On the other hand, it<em> is</em> legal to change the pointer
 5200  to point to some other value. When setting a variable of this type,
 5201  SWIG allocates a new string (using malloc or new) and changes the
 5202  pointer to point to the new value. However, repeated modifications of
 5203  the value will result in a memory leak since the old value is not
 5204  released.</p>
 5205 <h3><a name="SWIG_nn26">5.4.5 Arrays</a></h3>
 5206 <p> Arrays are fully supported by SWIG, but they are always handled as
 5207  pointers instead of mapping them to a special array object or list in
 5208  the target language. Thus, the following declarations :</p>
 5209 <div class="code">
 5210 <pre>
 5211 int foobar(int a[40]);
 5212 void grok(char *argv[]);
 5213 void transpose(double a[20][20]);
 5214 </pre>
 5215 </div>
 5216 <p> are processed as if they were really declared like this:</p>
 5217 <div class="code">
 5218 <pre>
 5219 int foobar(int *a);
 5220 void grok(char **argv);
 5221 void transpose(double (*a)[20]);
 5222 </pre>
 5223 </div>
 5224 <p> Like C, SWIG does not perform array bounds checking. It is up to the
 5225  user to make sure the pointer points to a suitably allocated region of
 5226  memory.</p>
 5227 <p> Multi-dimensional arrays are transformed into a pointer to an array
 5228  of one less dimension. For example:</p>
 5229 <div class="code">
 5230 <pre>
 5231 int [10];         // Maps to int *
 5232 int [10][20];     // Maps to int (*)[20]
 5233 int [10][20][30]; // Maps to int (*)[20][30]
 5234 </pre>
 5235 </div>
 5236 <p> It is important to note that in the C type system, a
 5237  multidimensional array <tt>a[][]</tt> is<b> NOT</b> equivalent to a
 5238  single pointer <tt>*a</tt> or a double pointer such as <tt>**a</tt>.
 5239  Instead, a pointer to an array is used (as shown above) where the
 5240  actual value of the pointer is the starting memory location of the
 5241  array. The reader is strongly advised to dust off their C book and
 5242  re-read the section on arrays before using them with SWIG.