"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"><!--
7
8 div.sectiontoc {
9 border-style: dotted;
10 border-width: 2px;
11 padding: 2pt;
12 }
13
14 h2 {
15 padding: 3px;
16 color: #000000;
17 border-bottom: 2px
18 solid #dddddd;
19 }
20
21 h3, h4 {
22 margin-left: 1em;
23 }
24
25 p,li,table,dl {
26 margin-left: 2em;
27 margin-right: 2em;
28 }
29
30 div.indent {
31 margin-left: 4em;
32 margin-right: 4em;
33 }
34
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 }
44
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 }
54
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 }
64
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 }
74
75 div.diagram li {
76 margin-left: 0;
77 }
78
79 ul li p {
80 margin-left: 0;
81 margin-right: 0;
82 }
83
84 ol li p {
85 margin-left: 0;
86 margin-right: 0;
87 }
88
89 dl dd p {
90 margin-left: 0;
91 margin-right: 0;
92 }
93
94 div.indent p {
95 margin-left: 0;
96 margin-right: 0;
97 }
98
99 pre, code, tt {
100 font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
101 }
102
103 body { font-family: serif; }
104
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">3.2.1.1 C#</a></li>
194 <li><a HREF="#Windows_java">3.2.1.2 Java</a></li>
195 <li><a HREF="#Windows_perl">3.2.1.3 Perl</a></li>
196 <li><a HREF="#Windows_python">3.2.1.4 Python</a></li>
197 <li><a HREF="#Windows_tcl">3.2.1.5 TCL</a></li>
198 <li><a HREF="#Windows_r">3.2.1.6 R</a></li>
199 <li><a HREF="#Windows_ruby">3.2.1.7 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">3.3.4.1 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">5.4.7.1 Simple renaming of specific identifiers</a>
288 </li>
289 <li><a HREF="#SWIG_ignore">5.4.7.2 Ignoring identifiers</a></li>
290 <li><a HREF="#SWIG_advanced_renaming">5.4.7.3 Advanced renaming support</a>
291 </li>
292 <li><a HREF="#SWIG_limiting_renaming">5.4.7.4 Limiting global renaming
293 rules</a></li>
294 <li><a HREF="#SWIG_chosen_unignore">5.4.7.5 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->()</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">7.2.1.1 Rvalue
446 reference inputs</a></li>
447 <li><a HREF="#CPlusPlus11_rvalue_reference_outputs">7.2.1.2 Rvalue
448 reference outputs</a></li>
449 <li><a HREF="#CPlusPlus11_move_only">7.2.1.3 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 %{ ... %} & "
588 ... " 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">12.4.4.1 shared_ptr basics</a></li>
629 <li><a HREF="#Library_shared_ptr_inheritance">12.4.4.2 shared_ptr and
630 inheritance</a></li>
631 <li><a HREF="#Library_shared_ptr_overloading">12.4.4.3 shared_ptr and
632 method overloading</a></li>
633 <li><a HREF="#Library_shared_ptr_templates">12.4.4.4 shared_ptr and
634 templates</a></li>
635 <li><a HREF="#Library_shared_ptr_directors">12.4.4.5 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">12.5.2.1 %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">14.4.4.1
723 $descriptor(type)</a></li>
724 <li><a HREF="#Typemaps_special_macro_typemap">14.4.4.2 $typemap(method,
725 typepattern)</a></li>
726 <li><a HREF="#Typemaps_special_macro_typemap_attribute">14.4.4.3
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 "in" typemap</a></li>
739 <li><a HREF="#Typemaps_nn27">14.5.2 "typecheck" typemap</a></li>
740 <li><a HREF="#Typemaps_nn28">14.5.3 "out" typemap</a></li>
741 <li><a HREF="#Typemaps_nn29">14.5.4 "arginit" typemap</a></li>
742 <li><a HREF="#Typemaps_nn30">14.5.5 "default" typemap</a></li>
743 <li><a HREF="#Typemaps_nn31">14.5.6 "check" typemap</a></li>
744 <li><a HREF="#Typemaps_nn32">14.5.7 "argout" typemap</a></li>
745 <li><a HREF="#Typemaps_nn33">14.5.8 "freearg" typemap</a></li>
746 <li><a HREF="#Typemaps_nn34">14.5.9 "newfree" typemap</a></li>
747 <li><a HREF="#Typemaps_ret">14.5.10 "ret" typemap</a></li>
748 <li><a HREF="#Typemaps_nn35">14.5.11 "memberin" typemap</a></li>
749 <li><a HREF="#Typemaps_nn36">14.5.12 "varin" typemap</a></li>
750 <li><a HREF="#Typemaps_nn37">14.5.13 "varout" typemap</a></li>
751 <li><a HREF="#Typemaps_throws_typemap">14.5.14 "throws" 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++ "this" 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">18.2.2.1 doxygen:notranslate</a></li>
862 <li><a HREF="#Doxygen_alias">18.2.2.2 doxygen:alias:<command-name></a></li>
863 <li><a HREF="#Doxygen_ignore">18.2.2.3 doxygen:ignore:<command-name></a></li>
864 <li><a HREF="#Doxygen_nolinktranslate">18.2.2.4 doxygen:nolinktranslate</a>
865 </li>
866 <li><a HREF="#Doxygen_nostripparams">18.2.2.5 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 "check" 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# <-> 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">25.4.5.1 Go Class Memory Management</a></li>
1102 <li><a HREF="#Go_class_inheritance">25.4.5.2 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">25.4.9.1 Example C++ code</a>
1111 </li>
1112 <li><a HREF="#Go_director_enable">25.4.9.2 Enable director feature</a></li>
1113 <li><a HREF="#Go_director_ctor_dtor">25.4.9.3 Constructor and destructor</a>
1114 </li>
1115 <li><a HREF="#Go_director_overriding">25.4.9.4 Override virtual methods</a>
1116 </li>
1117 <li><a HREF="#Go_director_base_methods">25.4.9.5 Call base methods</a></li>
1118 <li><a HREF="#Go_director_subclass">25.4.9.6 Subclass via embedding</a></li>
1119 <li><a HREF="#Go_director_finalizer">25.4.9.7 Memory management with
1120 runtime.SetFinalizer</a></li>
1121 <li><a HREF="#Go_director_foobargo_class">25.4.9.8 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 "Module"</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">27.2.8.1 Running SWIG from Visual
1188 Studio</a></li>
1189 <li><a HREF="#Java_nmake">27.2.8.2 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">27.3.5.1 Anonymous enums</a></li>
1204 <li><a HREF="#Java_typesafe_enums">27.3.5.2 Typesafe enums</a></li>
1205 <li><a HREF="#Java_proper_enums">27.3.5.3 Proper Java enums</a></li>
1206 <li><a HREF="#Java_typeunsafe_enums">27.3.5.4 Type unsafe enums</a></li>
1207 <li><a HREF="#Java_simple_enums">27.3.5.5 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">27.3.10.1 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">27.3.15.1 The shared_ptr
1228 Smart Pointer</a></li>
1229 <li><a HREF="#Java_smart_pointers_generic">27.3.15.2 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">27.4.1.1 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">27.4.2.1 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">27.4.3.1 Memory management</a></li>
1253 <li><a HREF="#Java_inheritance_mirroring">27.4.3.2 Inheritance</a></li>
1254 <li><a HREF="#Java_proxy_classes_gc">27.4.3.3 Proxy classes and garbage
1255 collection</a></li>
1256 <li><a HREF="#Java_pgcpp">27.4.3.4 The premature garbage collection
1257 prevention parameter for proxy class marshalling</a></li>
1258 <li><a HREF="#Java_multithread_libraries">27.4.3.5 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">27.4.5.1 Typesafe enum
1266 classes</a></li>
1267 <li><a HREF="#Java_proper_enums_classes">27.4.5.2 Proper Java enum
1268 classes</a></li>
1269 <li><a HREF="#Java_typeunsafe_enums_classes">27.4.5.3 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">27.5.7.1 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">28.3.1.1 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">28.3.2.1 Mac OS X</a></li>
1412 <li><a HREF="#Javascript_gtk">28.3.2.2 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">29.3.4.1 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">29.3.17.1 Compatibility Note</a></li>
1475 <li><a HREF="#Lua_nn29">29.3.17.2 Names</a></li>
1476 <li><a HREF="#Lua_nn30">29.3.17.3 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">30.3.12.1 The shared_ptr
1536 Smart Pointer</a></li>
1537 <li><a HREF="#Octave_smart_pointers_generic">30.3.12.2 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">32.2.6.1 Using -noproxy</a></li>
1649 <li><a HREF="#Php_nn2_6_2">32.2.6.2 Constructors and Destructors</a></li>
1650 <li><a HREF="#Php_nn2_6_3">32.2.6.3 Static Member Variables</a></li>
1651 <li><a HREF="#Php_nn2_6_4">32.2.6.4 Static Member Functions</a></li>
1652 <li><a HREF="#Php_nn2_6_5">32.2.6.5 Specifying Implemented Interfaces</a>
1653 </li>
1654 <li><a HREF="#Php_nn2_6_6">32.2.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">33.3.14.1 The shared_ptr
1710 Smart Pointer</a></li>
1711 <li><a HREF="#Python_smart_pointers_generic">33.3.14.2 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">33.4.2.1 Limitations</a></li>
1725 <li><a HREF="#Python_builtin_overloads">33.4.2.2 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">33.6.5.1 -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("autodoc")</a>
1792 <ul>
1793 <li><a HREF="#Python_nn68">33.10.2.1 %feature("autodoc", "0")</a></li>
1794 <li><a HREF="#Python_nn69">33.10.2.2 %feature("autodoc", "1")</a></li>
1795 <li><a HREF="#Python_autodoc2">33.10.2.3 %feature("autodoc", "2")</a></li>
1796 <li><a HREF="#Python_autodoc3">33.10.2.4 %feature("autodoc", "3")</a></li>
1797 <li><a HREF="#Python_nn70">33.10.2.5 %feature("autodoc", "docstring")</a>
1798 </li>
1799 </ul>
1800 </li>
1801 <li><a HREF="#Python_nn71">33.10.3 %feature("docstring")</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">33.11.6.1 Both
1820 modules in the same package</a></li>
1821 <li><a HREF="#Python_package_search_both_global_modules">33.11.6.2 Both
1822 modules are global</a></li>
1823 <li><a HREF="#Python_package_search_wrapper_split">33.11.6.3 Split
1824 modules custom configuration</a></li>
1825 <li><a HREF="#Python_custom_module_import">33.11.6.4 More on customizing
1826 the module import code</a></li>
1827 <li><a HREF="#Python_package_search_static">33.11.6.5 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">33.12.1.1 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">35.3.16.1 The shared_ptr
1910 Smart Pointer</a></li>
1911 <li><a HREF="#Ruby_smart_pointers_generic">35.3.16.2 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">35.3.17.1 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">35.7.6.1 "in" typemap</a></li>
1950 <li><a HREF="#Ruby_typecheck_typemap">35.7.6.2 "typecheck" typemap</a></li>
1951 <li><a HREF="#Ruby_out_typemap">35.7.6.3 "out" typemap</a></li>
1952 <li><a HREF="#Ruby_arginit_typemap">35.7.6.4 "arginit" typemap</a></li>
1953 <li><a HREF="#Ruby_default_typemap">35.7.6.5 "default" typemap</a></li>
1954 <li><a HREF="#Ruby_check_typemap">35.7.6.6 "check" typemap</a></li>
1955 <li><a HREF="#Ruby_argout_typemap_">35.7.6.7 "argout" typemap</a></li>
1956 <li><a HREF="#Ruby_freearg_typemap_">35.7.6.8 "freearg" typemap</a></li>
1957 <li><a HREF="#Ruby_newfree_typemap">35.7.6.9 "newfree" typemap</a></li>
1958 <li><a HREF="#Ruby_memberin_typemap">35.7.6.10 "memberin" typemap</a></li>
1959 <li><a HREF="#Ruby_varin_typemap">35.7.6.11 "varin" typemap</a></li>
1960 <li><a HREF="#Ruby_varout_typemap_">35.7.6.12 "varout" typemap</a></li>
1961 <li><a HREF="#Ruby_throws_typemap">35.7.6.13 "throws" typemap</a></li>
1962 <li><a HREF="#Ruby_directorin_typemap">35.7.6.14 directorin typemap</a></li>
1963 <li><a HREF="#Ruby_directorout_typemap">35.7.6.15 directorout typemap</a>
1964 </li>
1965 <li><a HREF="#Ruby_directorargout_typemap">35.7.6.16 directorargout
1966 typemap</a></li>
1967 <li><a HREF="#Ruby_ret_typemap">35.7.6.17 ret typemap</a></li>
1968 <li><a HREF="#Ruby_globalin_typemap">35.7.6.18 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">35.7.8.1 C Datatypes to Ruby Objects</a></li>
1975 <li><a HREF="#Ruby_nn43">35.7.8.2 Ruby Objects to C Datatypes</a></li>
1976 <li><a HREF="#Ruby_nn44">35.7.8.3 Macros for VALUE</a></li>
1977 <li><a HREF="#Ruby_nn45">35.7.8.4 Exceptions</a></li>
1978 <li><a HREF="#Ruby_nn46">35.7.8.5 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">35.7.12.1 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("autodoc")</a>
1997 <ul>
1998 <li><a HREF="#Ruby_nn68">35.8.2.1 %feature("autodoc", "0")</a></li>
1999 <li><a HREF="#Ruby_autodoc1">35.8.2.2 %feature("autodoc", "1")</a></li>
2000 <li><a HREF="#Ruby_autodoc2">35.8.2.3 %feature("autodoc", "2")</a></li>
2001 <li><a HREF="#Ruby_feature_autodoc3">35.8.2.4 %feature("autodoc", "3")</a>
2002 </li>
2003 <li><a HREF="#Ruby_nn70">35.8.2.5 %feature("autodoc", "docstring")</a></li>
2004 </ul>
2005 </li>
2006 <li><a HREF="#Ruby_nn71">35.8.3 %feature("docstring")</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">36.3.3.1 Argument passing</a></li>
2051 <li><a HREF="#Scilab_nn14">36.3.3.2 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">36.3.5.1 Constants</a></li>
2060 <li><a HREF="#Scilab_wrapping_enums">36.3.5.2 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">36.3.6.1
2066 Utility functions</a></li>
2067 <li><a HREF="#Scilab_wrapping_pointers_null_pointers">36.3.6.2 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">39.2.2.1 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">39.2.3.1 Simple types of bounded arrays</a></li>
2216 <li><a HREF="#Ocaml_nn14">39.2.3.2 Complex and unbounded arrays</a></li>
2217 <li><a HREF="#Ocaml_nn15">39.2.3.3 Using an object</a></li>
2218 <li><a HREF="#Ocaml_nn16">39.2.3.4 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">39.2.4.1 STL vector and string Example</a></li>
2225 <li><a HREF="#Ocaml_nn19">39.2.4.2 C++ Class Example</a></li>
2226 <li><a HREF="#Ocaml_nn20">39.2.4.3 Compiling the example</a></li>
2227 <li><a HREF="#Ocaml_nn21">39.2.4.4 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">39.2.5.1 Director Introduction</a></li>
2233 <li><a HREF="#Ocaml_nn24">39.2.5.2 Overriding Methods in Ocaml</a></li>
2234 <li><a HREF="#Ocaml_nn25">39.2.5.3 Director Usage Example</a></li>
2235 <li><a HREF="#Ocaml_nn26">39.2.5.4 Creating director objects</a></li>
2236 <li><a HREF="#Ocaml_nn27">39.2.5.5 Typemaps for directors, directorin,
2237 directorout, directorargout</a></li>
2238 <li><a HREF="#Ocaml_nn28">39.2.5.6 directorin typemap</a></li>
2239 <li><a HREF="#Ocaml_nn29">39.2.5.7 directorout typemap</a></li>
2240 <li><a HREF="#Ocaml_nn30">39.2.5.8 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">40.10.12.1 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">40.10.15.1 Supported status</a>
2322 </li>
2323 <li><a HREF="#Extending_experimental_status">40.10.15.2 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>
2396
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 "Introduction" 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 >= 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 "Example/index.html".</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>
2712
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 */
2895
2896 double My_variable = 3.0;
2897
2898 /* Compute factorial of n */
2899 int fact(int n) {
2900 if (n <= 1)
2901 return 1;
2902 else
2903 return n*fact(n-1);
2904 }
2905
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 %}
2927
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 > <b>swig -tcl example.i</b>
2944 unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b>
2945 unix > <b>gcc -shared example.o example_wrap.o -o example.so</b>
2946 unix > <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 > <b>swig -perl5 example.i</b>
2971 unix > <b>gcc -c example.c example_wrap.c \
2972 -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
2973 unix > <b>ld -G example.o example_wrap.o -o example.so</b> # This is for Solaris
2974 unix > <b>perl5.003
2975 use example;
2976 print example::fact(4), "\n";
2977 print example::my_mod(23, 7), "\n";
2978 print $example::My_variable + 4.5, "\n";
2979 <ctrl-d></b>
2980 24
2981 2
2982 7.5
2983 unix >
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 > <b>swig -python example.i</b>
2991 unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b>
2992 unix > <b>gcc -shared example.o example_wrap.o -o _example.so</b>
2993 unix > <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 "copyright", "credits" or "license" for more information.
2997 >>> <b>import example</b>
2998 >>> <b>example.fact(4)</b>
2999 24
3000 >>> <b>example.my_mod(23, 7)</b>
3001 2
3002 >>> <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 > <b>swig -perl5 -module example example.h</b>
3014 unix > <b>gcc -c example.c example_wrap.c \
3015 -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
3016 unix > <b>ld -G example.o example_wrap.o -o example.so</b>
3017 unix > <b>perl5.003
3018 use example;
3019 print example::fact(4), "\n";
3020 print example::my_mod(23, 7), "\n";
3021 print $example::My_variable + 4.5, "\n";
3022 <ctrl-d></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>
3098
3099 # This is a CMake example for Python
3100
3101 FIND_PACKAGE(SWIG REQUIRED)
3102 INCLUDE(${SWIG_USE_FILE})
3103
3104 FIND_PACKAGE(PythonLibs)
3105 INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})
3106
3107 INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
3108
3109 SET(CMAKE_SWIG_FLAGS "")
3110
3111 SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)
3112 SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
3113 SWIG_ADD_MODULE(example python example.i example.cxx)
3114 SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
3115
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 "philosophy" 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 "shooting yourself in the foot" 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>
3158
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">3.2.1.1 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">3.2.1.2 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">3.2.1.3 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">3.2.1.4 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">3.2.1.5 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 8.3.3.3
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">3.2.1.6 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">3.2.1.7 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>& "C:\Tools\nuget" 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>"Visual
3382 Studio 16 2019 -A x64"</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
3392
3393 $env:PATH="C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;" + $env:PATH
3394 $PCRE_ROOT="C:\Tools\pcre2\PCRE2.10.39.0"
3395 $PCRE_PLATFORM="x64"
3396
3397 cmake -G "Visual Studio 16 2019" -A "x64" `
3398 -DCMAKE_INSTALL_PREFIX="C:/swig/install2" `
3399 -DCMAKE_C_FLAGS="/DPCRE2_STATIC" `
3400 -DCMAKE_CXX_FLAGS="/DPCRE2_STATIC" `
3401 -DPCRE2_INCLUDE_DIR="$PCRE_ROOT/include" `
3402 -DPCRE2_LIBRARY="$PCRE_ROOT/lib/pcre2-8-static.lib" `
3403 -S . -B build
3404
3405 cmake --build build --config Release
3406 cmake --install build --config Release
3407
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 > Debugging > 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 "do you wish to continue with the post install?"</li>
3497 <li>Answer y to the "do you have MinGW installed?"</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">3.3.4.1 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 <windows.i>
3581
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 <windows.i>
3600 %include "export_lib.h"
3601 %include "bar.h"
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 "export_lib.h"
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 "bar.h"
3627 </pre>
3628 </div><HR NOSHADE>
3629 <h1><a name="Scripting">4 Scripting Languages</a></h1>
3630
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 "commands." 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 "wrapper"
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 <= 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 "wrapper" 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->result = "wrong # args";
3727 return TCL_ERROR;
3728 }
3729 arg0 = atoi(argv[1]);
3730 result = fact(arg0);
3731 sprintf(interp->result, "%d", result);
3732 return TCL_OK;
3733 }
3734
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, "fact", 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 "<tt>fact</tt>
3752 " 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 "get" function is invoked. Similarly, whenever the
3777 value of a variable is changed, a "set" 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 };
3816
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);
3830
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 >>> v = Vector()
3869 >>> v.x = 3
3870 >>> v.y = 4
3871 >>> v.z = -13
3872 >>> ...
3873 >>> 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->{x} = 3;
3881 $v->{y} = 4;
3882 $v->{z} = -13;
3883
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
3891
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
3916
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 >>> import graph
3952 Traceback (innermost last):
3953 File "<stdin>", line 1, in ?
3954 File "/home/sci/data1/beazley/graph/graph.py", 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 >>>
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 "<tt>libgraph.so</tt>" 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>
3993
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> -<lang></em> -help</tt> for language<em> <lang></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
4119
4120 Experimental Target Language Options
4121 -mzscheme - Generate MzScheme/Racket wrappers
4122 -ocaml - Generate OCaml wrappers
4123
4124 General Options
4125 -addextern - Add extra extern declarations
4126 -c++ - Enable C++ processing
4127 -co <file> - Check <file> 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 <ext> - Change file extension of generated C++ files to <ext>
4131 (default is cxx)
4132 -copyright - Display copyright notices
4133 -debug-classes - Display information about the classes found in the interface
4134 -debug-module <n>- Display module parse tree at stages 1-4, <n> 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 <n> - Display entire parse tree at stages 1-4, <n> 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<symbol> - Define a symbol <symbol> (for conditional compilation)
4150 -E - Preprocess only, does not generate wrapper code
4151 -external-runtime [file] - Export the SWIG runtime stack
4152 -fakeversion <v>- Make SWIG fake the program version number to <v>
4153 -fcompact - Compile in compact mode
4154 -features <list>- Set global features, where <list> 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<dir> - Look for SWIG files in directory <dir>
4164 -ignoremissing - Ignore missing include files
4165 -importall - Follow all #include statements as imports
4166 -includeall - Follow all #include statements
4167 -l<ifile> - Include SWIG library file <ifile>
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 <file>', except `-E' is not implied
4172 -MF <file> - Generate dependencies into <file> 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 <name> - Set module name to <name>
4176 -MP - Generate phony targets for all dependencies
4177 -MT <target> - 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 <outfile> - Set name of C/C++ output file to <outfile>
4191 -oh <headfile> - Set name of C++ output header file for directors to <headfile>
4192 -outcurrentdir - Set default output dir to current dir instead of input file's path
4193 -outdir <dir> - Set language specific files output directory to <dir>
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<list> - Suppress/add warning messages, eg -w401,+321 - see Warnings.html
4205 -xmlout <file> - Write XML version of the parse tree to <file> 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 "myheader.h"
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 "<a href="#Preprocessor">Preprocessor</a>" 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 "<tt>%</tt>" 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 */
4343
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;
4367
4368 /* Extra declarator grouping */
4369 Matrix (foo); // A global variable
4370
4371 /* Extra declarator grouping in parameters */
4372 void bar(Spam (Grok)(Doh));
4373
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&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
4432
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 "1.1"
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 >>> example.sin(3)
4465 5.2335956
4466 >>> example.strcmp('Dave', 'Mike')
4467 -1
4468 >>> print example.cvar.Foo
4469 42
4470 >>> print example.STATUS
4471 50
4472 >>> 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 "foo" 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;
4585
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
4594
4595 # Python
4596 cvar.foo = 3.5 # Set foo to 3.5
4597 print cvar.foo # Print value of foo
4598
4599 # Perl
4600 $foo = 3.5; # Set foo to 3.5
4601 print $foo, "\n"; # Print value of foo
4602
4603 # Ruby
4604 Module.foo = 3.5 # Set foo to 3.5
4605 print Module.foo, "\n" # 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 "hello world" // A string constant
4631 #define NEWLINE '\n' // Character constant
4632
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
4639
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
4652
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 "read-only" 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 ...
4778
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 "NULL" 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 *);
4890
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, "r")
4902 f2 = fopen(target, "w")
4903 buffer = malloc(8192)
4904 nbytes = fread(buffer, 8192, 1, f1)
4905 while (nbytes > 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 "<tt>Matrix</tt>" 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>
4954
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 "sys/types.h"
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 &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 }
5130
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 >>> set_foo("Hello World")
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 = "1.0";
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] = "1.0";
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 = "Hello World\n";
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.