Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <!-- Hand-written HTML --> | |
3 | <html> | |
4 | <head> | |
5 | <title>SWIG and Guile</title> | |
6 | <link rel="stylesheet" type="text/css" href="style.css"> | |
7 | </head> | |
8 | ||
9 | <body bgcolor="#ffffff"> | |
10 | ||
11 | <H1><a name="Guile"></a>18 SWIG and Guile</H1> | |
12 | <!-- INDEX --> | |
13 | <div class="sectiontoc"> | |
14 | <ul> | |
15 | <li><a href="#Guile_nn2">Meaning of "Module"</a> | |
16 | <li><a href="#Guile_nn3">Using the SCM or GH Guile API</a> | |
17 | <li><a href="#Guile_nn4">Linkage</a> | |
18 | <ul> | |
19 | <li><a href="#Guile_nn5">Simple Linkage</a> | |
20 | <li><a href="#Guile_nn6">Passive Linkage</a> | |
21 | <li><a href="#Guile_nn7">Native Guile Module Linkage</a> | |
22 | <li><a href="#Guile_nn8">Old Auto-Loading Guile Module Linkage</a> | |
23 | <li><a href="#Guile_nn9">Hobbit4D Linkage</a> | |
24 | </ul> | |
25 | <li><a href="#Guile_nn10">Underscore Folding</a> | |
26 | <li><a href="#Guile_nn11">Typemaps</a> | |
27 | <li><a href="#Guile_nn12">Representation of pointers as smobs</a> | |
28 | <ul> | |
29 | <li><a href="#Guile_nn13">GH Smobs</a> | |
30 | <li><a href="#Guile_nn14">SCM Smobs</a> | |
31 | <li><a href="#Guile_nn15">Garbage Collection</a> | |
32 | </ul> | |
33 | <li><a href="#Guile_nn16">Exception Handling</a> | |
34 | <li><a href="#Guile_nn17">Procedure documentation</a> | |
35 | <li><a href="#Guile_nn18">Procedures with setters</a> | |
36 | <li><a href="#Guile_nn19">GOOPS Proxy Classes</a> | |
37 | <ul> | |
38 | <li><a href="#Guile_nn20">Naming Issues</a> | |
39 | <li><a href="#Guile_nn21">Linking</a> | |
40 | </ul> | |
41 | </ul> | |
42 | </div> | |
43 | <!-- INDEX --> | |
44 | ||
45 | ||
46 | ||
47 | <p> | |
48 | This section details guile-specific support in SWIG. | |
49 | ||
50 | <H2><a name="Guile_nn2"></a>18.1 Meaning of "Module"</H2> | |
51 | ||
52 | ||
53 | <p> | |
54 | There are three different concepts of "module" involved, defined | |
55 | separately for SWIG, Guile, and Libtool. To avoid horrible confusion, | |
56 | we explicitly prefix the context, e.g., "guile-module". | |
57 | ||
58 | <H2><a name="Guile_nn3"></a>18.2 Using the SCM or GH Guile API</H2> | |
59 | ||
60 | ||
61 | <p>The guile module can currently export wrapper files that use the guile GH interface or the | |
62 | SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig | |
63 | to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-scm" argument | |
64 | is the default. The "-scm" wrapper generation assumes a guile version >= 1.6 and has several advantages over | |
65 | the "-gh" wrapper generation including garbage collection and GOOPS support. | |
66 | The "-gh" wrapper generation can be used for older versions of guile. | |
67 | The guile GH wrapper code generation is depreciated and the | |
68 | SCM interface is the default. The SCM and GH interface differ greatly in how they store | |
69 | pointers and have completely different run-time code. See below for more info. | |
70 | ||
71 | <p>The GH interface to guile is deprecated. Read more about why in the | |
72 | <a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>. | |
73 | The idea of the GH interface was to provide a high level API that other languages and projects | |
74 | could adopt. This was a good idea, but didn't pan out well for general development. But for the | |
75 | specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for | |
76 | using a high level API. So even though the GH interface is depreciated, SWIG will continue to use | |
77 | the GH interface and provide mappings from the GH interface to whatever API we need. | |
78 | We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions | |
79 | which map easily. All the guile typemaps like typemaps.i and std_vector.i | |
80 | will continue to use the GH functions to do things like create lists of values, convert strings to | |
81 | integers, etc. Then every language module will define a mapping between the GH interface and | |
82 | whatever custom API the language uses. This is currently implemented by the guile module to use | |
83 | the SCM guile API rather than the GH guile API. | |
84 | For example, here are some of the current mapping file for the SCM API</p> | |
85 | ||
86 | <div class="code"><pre> | |
87 | ||
88 | #define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED)) | |
89 | #define gh_apply(a, b) scm_apply(a, b, SCM_EOL) | |
90 | #define gh_bool2scm SCM_BOOL | |
91 | #define gh_boolean_p SCM_BOOLP | |
92 | #define gh_car SCM_CAR | |
93 | #define gh_cdr SCM_CDR | |
94 | #define gh_cons scm_cons | |
95 | #define gh_double2scm scm_make_real | |
96 | ... | |
97 | </pre></div> | |
98 | ||
99 | <p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced | |
100 | by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper; | |
101 | the wrapper will look exactly like it was generated | |
102 | for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_, | |
103 | but there is no reason other languages (like mzscheme or chicken) couldn't also use this. | |
104 | If that happens, there is A LOT less code duplication in the standard typemaps.</p> | |
105 | ||
106 | <H2><a name="Guile_nn4"></a>18.3 Linkage</H2> | |
107 | ||
108 | ||
109 | <p> | |
110 | Guile support is complicated by a lack of user community cohesiveness, | |
111 | which manifests in multiple shared-library usage conventions. A set of | |
112 | policies implementing a usage convention is called a <b>linkage</b>. | |
113 | ||
114 | <H3><a name="Guile_nn5"></a>18.3.1 Simple Linkage</H3> | |
115 | ||
116 | ||
117 | <p> | |
118 | The default linkage is the simplest; nothing special is done. In this | |
119 | case the function <code>SWIG_init()</code> is exported. Simple linkage | |
120 | can be used in several ways: | |
121 | </p> | |
122 | ||
123 | <ul> | |
124 | <li><b>Embedded Guile, no modules.</b> You want to embed a Guile | |
125 | interpreter into your program; all bindings made by SWIG shall show up | |
126 | in the root module. Then call <code>SWIG_init()</code> in the | |
127 | <code>inner_main()</code> function. See the "simple" and "matrix" examples under | |
128 | <code>Examples/guile</code>. | |
129 | ||
130 | <li><p><b>Dynamic module mix-in.</b> You want to create a Guile module | |
131 | using <code>define-module</code>, containing both Scheme code and | |
132 | bindings made by SWIG; you want to load the SWIG modules as shared | |
133 | libraries into Guile.</p> | |
134 | <div class="targetlang"> | |
135 | <pre> | |
136 | (define-module (my module)) | |
137 | (define my-so (dynamic-link "./example.so")) | |
138 | (dynamic-call "SWIG_init" my-so) ; make SWIG bindings | |
139 | ;; Scheme definitions can go here | |
140 | </pre> | |
141 | </div> | |
142 | ||
143 | <p> | |
144 | Newer Guile versions provide a shorthand for <code>dynamic-link</code> | |
145 | and <code>dynamic-call</code>: | |
146 | </p> | |
147 | ||
148 | <div class="targetlang"> | |
149 | <pre> | |
150 | (load-extension "./example.so" "SWIG_init") | |
151 | </pre> | |
152 | </div> | |
153 | ||
154 | <p> | |
155 | You need to explicitly export those bindings made by SWIG that you | |
156 | want to import into other modules: | |
157 | </p> | |
158 | ||
159 | <div class="targetlang"> | |
160 | <pre> | |
161 | (export foo bar) | |
162 | </pre> | |
163 | </div> | |
164 | ||
165 | <p> | |
166 | In this example, the procedures <code>foo</code> and <code>bar</code> | |
167 | would be exported. Alternatively, you can export all bindings with the | |
168 | following module-system hack: | |
169 | </p> | |
170 | ||
171 | <div class="targetlang"> | |
172 | <pre> | |
173 | (module-map (lambda (sym var) | |
174 | (module-export! (current-module) (list sym))) | |
175 | (current-module)) | |
176 | </pre> | |
177 | </div> | |
178 | ||
179 | <p>SWIG can also generate this Scheme stub (from | |
180 | <code>define-module</code> up to <code>export</code>) | |
181 | semi-automagically if you pass it the command-line argument | |
182 | <code>-scmstub</code>. The code will be exported in a file called | |
183 | <code><i>module</i>.scm</code> in the directory specified by <code>-outdir</code> | |
184 | or the current directory if <code>-outdir</code> is not specified. | |
185 | Since SWIG doesn't know how | |
186 | to load your extension module (with <code>dynamic-link</code> or | |
187 | <code>load-extension</code>), you need to supply this | |
188 | information by including a directive like this in the interface file: | |
189 | </p> | |
190 | ||
191 | <div class="code"> | |
192 | <pre> | |
193 | %scheme %{ (load-extension "./example.so" "SWIG_init") %} | |
194 | </pre> | |
195 | </div> | |
196 | ||
197 | <p> | |
198 | (The <code>%scheme</code> directive allows to insert arbitrary Scheme | |
199 | code into the generated file <code><var>module.scm</var></code>; it is | |
200 | placed between the <code>define-module</code> form and the | |
201 | <code>export</code> form.) | |
202 | </p> | |
203 | </ul> | |
204 | ||
205 | <p>If you want to include several SWIG modules, you would need to rename | |
206 | <code>SWIG_init</code> via a preprocessor define to avoid symbol | |
207 | clashes. For this case, however, passive linkage is available. | |
208 | ||
209 | <H3><a name="Guile_nn6"></a>18.3.2 Passive Linkage</H3> | |
210 | ||
211 | ||
212 | <p>Passive linkage is just like simple linkage, but it generates an | |
213 | initialization function whose name is derived from the module and | |
214 | package name (see below). | |
215 | ||
216 | <p>You should use passive linkage rather than simple linkage when you | |
217 | are using multiple modules. | |
218 | ||
219 | <H3><a name="Guile_nn7"></a>18.3.3 Native Guile Module Linkage</H3> | |
220 | ||
221 | ||
222 | <p>SWIG can also generate wrapper code that does all the Guile module | |
223 | declarations on its own if you pass it the <code>-Linkage | |
224 | module</code> command-line option. This requires Guile 1.5.0 or later. | |
225 | ||
226 | <p>The module name is set with the <code>-package</code> and | |
227 | <code>-module</code> command-line options. Suppose you want to define | |
228 | a module with name <code>(my lib foo)</code>; then you would have to | |
229 | pass the options <code>-package <var>my</var>/<var>lib</var> -module | |
230 | <var>foo</var></code>. Note that the last part of the name can also be set | |
231 | via the SWIG directive <code>%module</code>. | |
232 | ||
233 | <p>You can use this linkage in several ways: | |
234 | ||
235 | <ul> | |
236 | <li><b>Embedded Guile with SWIG modules.</b> You want to embed a Guile | |
237 | interpreter into your program; the SWIG bindings shall be put into | |
238 | different modules. Simply call the function | |
239 | <code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code> | |
240 | in the <code>inner_main()</code> function. | |
241 | ||
242 | <li><b>Dynamic Guile modules.</b> You want to load the SWIG modules as | |
243 | shared libraries into Guile; all bindings are automatically put in | |
244 | newly created Guile modules. | |
245 | <div class="targetlang"> | |
246 | <pre> | |
247 | (define my-so (dynamic-link "./foo.so")) | |
248 | ;; create new module and put bindings there: | |
249 | (dynamic-call "scm_init_my_modules_foo_module" my-so) | |
250 | </pre> | |
251 | </div> | |
252 | Newer Guile versions have a shorthand procedure for this: | |
253 | <div class="targetlang"> | |
254 | <pre> | |
255 | (load-extension "./foo.so" "scm_init_my_modules_foo_module") | |
256 | </pre> | |
257 | </div> | |
258 | </ul> | |
259 | ||
260 | <H3><a name="Guile_nn8"></a>18.3.4 Old Auto-Loading Guile Module Linkage</H3> | |
261 | ||
262 | ||
263 | <p>Guile used to support an autoloading facility for object-code | |
264 | modules. This support has been marked deprecated in version 1.4.1 and | |
265 | is going to disappear sooner or later. SWIG still supports building | |
266 | auto-loading modules if you pass it the <code>-Linkage ltdlmod</code> | |
267 | command-line option. | |
268 | ||
269 | <p>Auto-loading worked like this: Suppose a module with name <code>(my | |
270 | lib foo)</code> is required and not loaded yet. Guile will then search | |
271 | all directories in its search path | |
272 | for a Scheme file <code>my/modules/foo.scm</code> or a shared library | |
273 | <code><var>my</var>/<var>modules</var>/lib<var>foo</var>.so</code> (or | |
274 | <code><var>my</var>/<var>modules</var>/lib<var>foo</var>.la</code>; | |
275 | see the GNU libtool documentation). If a | |
276 | shared library is found that contains the symbol | |
277 | <code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>, | |
278 | the library is loaded, and the function at that symbol is called with | |
279 | no arguments in order to initialize the module. | |
280 | ||
281 | <p>When invoked with the <code>-Linkage ltdlmod</code> command-line | |
282 | option, SWIG generates an exported module initialization function with | |
283 | an appropriate name. | |
284 | ||
285 | ||
286 | <H3><a name="Guile_nn9"></a>18.3.5 Hobbit4D Linkage</H3> | |
287 | ||
288 | ||
289 | <p> | |
290 | The only other linkage supported at this time creates shared object | |
291 | libraries suitable for use by hobbit's <code>(hobbit4d link)</code> | |
292 | guile module. This is called the "hobbit" linkage, and requires also | |
293 | using the "-package" command line option to set the part of the module | |
294 | name before the last symbol. For example, both command lines: | |
295 | </p> | |
296 | ||
297 | <div class="shell"> | |
298 | <pre> | |
299 | swig -guile -package my/lib foo.i | |
300 | swig -guile -package my/lib -module foo foo.i | |
301 | </pre> | |
302 | </div> | |
303 | ||
304 | <p> | |
305 | would create module <code>(my lib foo)</code> (assuming in the first | |
306 | case foo.i declares the module to be "foo"). The installed files are | |
307 | my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very | |
308 | experimental; the (hobbit4d link) conventions are not well understood. | |
309 | </p> | |
310 | ||
311 | <H2><a name="Guile_nn10"></a>18.4 Underscore Folding</H2> | |
312 | ||
313 | ||
314 | <p> | |
315 | Underscores are converted to dashes in identifiers. Guile support may | |
316 | grow an option to inhibit this folding in the future, but no one has | |
317 | complained so far. | |
318 | ||
319 | <p>You can use the SWIG directives <code>%name</code> and | |
320 | <code>%rename</code> to specify the Guile name of the wrapped | |
321 | functions and variables (see CHANGES). | |
322 | ||
323 | <H2><a name="Guile_nn11"></a>18.5 Typemaps</H2> | |
324 | ||
325 | ||
326 | <p> | |
327 | The Guile module handles all types via typemaps. This | |
328 | information is read from <code>Lib/guile/typemaps.i</code>. | |
329 | ||
330 | Some non-standard typemap substitutions are supported: | |
331 | <ul> | |
332 | <li><code>$descriptor</code> expands to a type descriptor for use with | |
333 | the <code>SWIG_NewPointerObj()</code> and | |
334 | <code>SWIG_ConvertPtr</code> functions. | |
335 | <li>For pointer types, <code>$*descriptor</code> expands to a | |
336 | descriptor for the direct base type (i.e., one pointer is stripped), | |
337 | whereas <code>$basedescriptor</code> expands to a | |
338 | descriptor for the base type (i.e., all pointers are stripped). | |
339 | </ul> | |
340 | ||
341 | <p>A function returning <code>void</code> (more precisely, a function | |
342 | whose <code>out</code> typemap returns <code>SCM_UNSPECIFIED</code>) is | |
343 | treated as returning no values. In <code>argout</code> typemaps, one | |
344 | can use the macro <code>GUILE_APPEND_RESULT</code> in order to append | |
345 | a value to the list of function return values. | |
346 | ||
347 | <p>Multiple values can be passed up to Scheme in one of three ways: | |
348 | <ul> | |
349 | <li><p><em>Multiple values as lists.</em> | |
350 | By default, if more than one value is to | |
351 | be returned, a list of the values is created and returned; to switch | |
352 | back to this behavior, use</p> | |
353 | ||
354 | <div class="code"> | |
355 | <pre> | |
356 | %values_as_list;</pre> | |
357 | </div> | |
358 | ||
359 | <li><p><em>Multiple values as vectors.</em> | |
360 | By issuing | |
361 | </p> | |
362 | ||
363 | <div class="code"> | |
364 | <pre> | |
365 | %values_as_vector;</pre> | |
366 | </div> | |
367 | ||
368 | <p> | |
369 | vectors instead of lists will be used. | |
370 | <li><p><em>Multiple values for multiple-value continuations.</em> | |
371 | <strong>This is the most elegant way.</strong> By issuing | |
372 | </p> | |
373 | ||
374 | <div class="code"> | |
375 | <pre> | |
376 | %multiple_values;</pre> | |
377 | </div> | |
378 | ||
379 | <p> | |
380 | multiple values are passed to the multiple-value | |
381 | continuation, as created by <code>call-with-values</code> or the | |
382 | convenience macro <code>receive</code>. The latter is available if you | |
383 | issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your | |
384 | <code>divide</code> function | |
385 | wants to return two values, a quotient and a remainder, you can write: | |
386 | </p> | |
387 | ||
388 | <div class="targetlang"> | |
389 | <pre> | |
390 | (receive (quotient remainder) | |
391 | (divide 35 17) | |
392 | <var>body</var>...) | |
393 | </pre> | |
394 | </div> | |
395 | ||
396 | <p> | |
397 | In <code><var>body</var></code>, the first result of | |
398 | <code>divide</code> will be bound to the variable | |
399 | <code>quotient</code>, and the second result to <code>remainder</code>. | |
400 | </p> | |
401 | ||
402 | </ul> | |
403 | ||
404 | <p> | |
405 | See also the "multivalue" example. | |
406 | </p> | |
407 | ||
408 | <H2><a name="Guile_nn12"></a>18.6 Representation of pointers as smobs</H2> | |
409 | ||
410 | ||
411 | <p> | |
412 | For pointer types, SWIG uses Guile smobs. SWIG smobs print | |
413 | like this: <code>#<swig struct xyzzy * 0x1234affe></code> Two of | |
414 | them are <code>equal?</code> if and only if they have the same type | |
415 | and value. | |
416 | ||
417 | <p> | |
418 | To construct a Scheme object from a C pointer, the wrapper code calls | |
419 | the function <code>SWIG_NewPointerObj()</code>, passing a pointer to a | |
420 | struct representing the pointer type. The type index to store in the | |
421 | upper half of the CAR is read from this struct. | |
422 | To get the pointer represented by a smob, the wrapper code calls the | |
423 | function <code>SWIG_ConvertPtr()</code>, passing a pointer to a struct | |
424 | representing the expected pointer type. See also | |
425 | <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>. | |
426 | If the Scheme object passed was not a SWIG smob representing a compatible | |
427 | pointer, a <code>wrong-type-arg</code> exception is raised. | |
428 | ||
429 | <H3><a name="Guile_nn13"></a>18.6.1 GH Smobs</H3> | |
430 | ||
431 | ||
432 | <p> | |
433 | In earlier versions of SWIG, C pointers were represented as Scheme | |
434 | strings containing a hexadecimal rendering of the pointer value and a | |
435 | mangled type name. As Guile allows registering user types, so-called | |
436 | "smobs" (small objects), a much cleaner representation has been | |
437 | implemented now. The details will be discussed in the following. | |
438 | </p> | |
439 | ||
440 | <p> A smob is a cons cell where the lower half of the CAR contains the smob type | |
441 | tag, while the upper half of the CAR and the whole CDR are available. Every | |
442 | module creates its own smob type in the clientdata field of the module. So the | |
443 | lower 16 bits of the car of the smob store the tag and the upper 16 bits store | |
444 | the index this type is in the array. We can then, given a smob, find its | |
445 | swig_type_info struct by using the tag (lower 16 bits of car) to find which | |
446 | module this type is in (since each tag is unique for the module). Then we use | |
447 | the upper 16 bits to index into the array of types attached to this module. | |
448 | Looking up the module from the tag is worst case O(# of modules) but average | |
449 | case O(1). This is because the modules are stored in a circularly linked list, | |
450 | and when we start searching the modules for the tag, we start looking with the | |
451 | module that the function doing the lookup is in. SWIG_Guile_ConvertPtr() takes | |
452 | as its first argument the swig_module_info * of the calling function, which is | |
453 | where we start comparing tags. Most types will be looked up in the same module | |
454 | that created them, so the first module we check will most likely be correct. | |
455 | Once we have a swig_type_info structure, we loop through the linked list of | |
456 | casts, using pointer comparisons.</p> | |
457 | ||
458 | <H3><a name="Guile_nn14"></a>18.6.2 SCM Smobs</H3> | |
459 | ||
460 | ||
461 | <p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg. | |
462 | The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig". | |
463 | The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described | |
464 | below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2() | |
465 | The first word of data is the pointer to the object and the second word of data is the swig_type_info * | |
466 | structure describing this type. This is a lot easier than the GH interface above because we can store | |
467 | a pointer to the type info structure right in the type. With the GH interface, there was not enough | |
468 | room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address" | |
469 | in the smob tag. If a generated GOOPS module has been loaded, smobs will be wrapped by the corresponding | |
470 | GOOPS class.</p> | |
471 | ||
472 | ||
473 | <H3><a name="Guile_nn15"></a>18.6.3 Garbage Collection</H3> | |
474 | ||
475 | ||
476 | <p>Garbage collection is a feature of the new SCM interface, and it is automatically included | |
477 | if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile >1.6. | |
478 | Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer | |
479 | to the destructor for this type. The destructor is the generated wrapper around the delete function. | |
480 | So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for | |
481 | the wrapped delete function. So the only way to delete an object is from the garbage collector, since the | |
482 | delete function is not available to scripts. How swig determines if a type should be garbage collected | |
483 | is exactly like described in <a href="Customization.html#ownership"> | |
484 | Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and | |
485 | the guile module replaces $owner with 0 or 1 depending on feature:new.</p> | |
486 | ||
487 | <H2><a name="Guile_nn16"></a>18.7 Exception Handling</H2> | |
488 | ||
489 | ||
490 | <p> | |
491 | SWIG code calls <code>scm_error</code> on exception, using the following | |
492 | mapping: | |
493 | ||
494 | <div class="code"> | |
495 | <pre> | |
496 | MAP(SWIG_MemoryError, "swig-memory-error"); | |
497 | MAP(SWIG_IOError, "swig-io-error"); | |
498 | MAP(SWIG_RuntimeError, "swig-runtime-error"); | |
499 | MAP(SWIG_IndexError, "swig-index-error"); | |
500 | MAP(SWIG_TypeError, "swig-type-error"); | |
501 | MAP(SWIG_DivisionByZero, "swig-division-by-zero"); | |
502 | MAP(SWIG_OverflowError, "swig-overflow-error"); | |
503 | MAP(SWIG_SyntaxError, "swig-syntax-error"); | |
504 | MAP(SWIG_ValueError, "swig-value-error"); | |
505 | MAP(SWIG_SystemError, "swig-system-error"); | |
506 | </pre> | |
507 | </div> | |
508 | ||
509 | <p> | |
510 | The default when not specified here is to use "swig-error". | |
511 | See Lib/exception.i for details. | |
512 | ||
513 | <H2><a name="Guile_nn17"></a>18.8 Procedure documentation</H2> | |
514 | ||
515 | ||
516 | <p>If invoked with the command-line option <code>-procdoc | |
517 | <var>file</var></code>, SWIG creates documentation strings for the | |
518 | generated wrapper functions, describing the procedure signature and | |
519 | return value, and writes them to <var>file</var>. You need Guile 1.4 | |
520 | or later to make use of the documentation files. | |
521 | ||
522 | <p>SWIG can generate documentation strings in three formats, which are | |
523 | selected via the command-line option <code>-procdocformat | |
524 | <var>format</var></code>: | |
525 | <ul> | |
526 | <li><code>guile-1.4</code> (default): Generates a format suitable for Guile 1.4. | |
527 | <li><code>plain</code>: Generates a format suitable for Guile 1.4.1 and | |
528 | later. | |
529 | <li><code>texinfo</code>: Generates texinfo source, which must be run | |
530 | through texinfo in order to get a format suitable for Guile 1.4.1 and | |
531 | later. | |
532 | </ul> | |
533 | ||
534 | <p>You need to register the generated documentation file with Guile | |
535 | like this: | |
536 | ||
537 | <div class="targetlang"> | |
538 | <pre> | |
539 | (use-modules (ice-9 documentation)) | |
540 | (set! documentation-files | |
541 | (cons "<var>file</var>" documentation-files)) | |
542 | </pre> | |
543 | </div> | |
544 | ||
545 | <p>Documentation strings can be configured using the Guile-specific | |
546 | typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for | |
547 | details. | |
548 | ||
549 | <H2><a name="Guile_nn18"></a>18.9 Procedures with setters</H2> | |
550 | ||
551 | ||
552 | <p>For global variables, SWIG creates a single wrapper procedure | |
553 | <code>(<var>variable</var> :optional value)</code>, which is used for | |
554 | both getting and setting the value. For struct members, SWIG creates | |
555 | two wrapper procedures <code>(<var>struct</var>-<var>member</var>-get | |
556 | pointer)</code> and <code>(<var>struct-member</var>-set pointer value)</code>. | |
557 | ||
558 | <p>If invoked with the command-line option <code>-emit-setters</code> | |
559 | (<em>recommended</em>), | |
560 | SWIG will additionally create procedures with setters. For global | |
561 | variables, the procedure-with-setter <code><var>variable</var></code> | |
562 | is created, so you can use <code>(<var>variable</var>)</code> to get | |
563 | the value and <code>(set! (<var>variable</var>) | |
564 | <var>value</var>)</code> to set it. For struct members, the | |
565 | procedure-with-setter <code><var>struct</var>-<var>member</var></code> | |
566 | is created, so you can use <code>(<var>struct</var>-<var>member</var> | |
567 | <var>pointer</var>)</code> to get the value and <code>(set! | |
568 | (<var>struct</var>-<var>member</var> <var>pointer</var>) | |
569 | <var>value</var>)</code> to set it. | |
570 | ||
571 | <p>If invoked with the command-line option <code>-only-setters</code>, | |
572 | SWIG will <em>only</em> create procedures with setters, i.e., for | |
573 | struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get | |
574 | pointer)</code> and <code>(<var>struct-member</var>-set pointer | |
575 | value)</code> are <em>not</em> generated. | |
576 | ||
577 | <H2><a name="Guile_nn19"></a>18.10 GOOPS Proxy Classes</H2> | |
578 | ||
579 | ||
580 | <p>SWIG can also generate classes and generic functions for use with | |
581 | Guile's Object-Oriented Programming System (GOOPS). GOOPS is a | |
582 | sophisticated object system in the spirit of the Common Lisp Object | |
583 | System (CLOS). | |
584 | ||
585 | <p>GOOPS support is | |
586 | only available with the new SCM interface (enabled with the | |
587 | <code>-scm</code> command-line option of SWIG). To enable GOOPS | |
588 | support, pass the <code>-proxy</code> argument to | |
589 | swig. This will export the GOOPS wrapper definitions into the | |
590 | <code><i>module</i>.scm</code> file in the directory specified by -outdir or the | |
591 | current directory. GOOPS support requires either passive or module linkage.</p> | |
592 | ||
593 | <p>The generated file will contain definitions of GOOPS classes mimicking the C++ class hierarchy. | |
594 | <p>Enabling GOOPS support implies <code>-emit-setters</code>. | |
595 | ||
596 | <p>If <code>-emit-slot-accessors</code> is also passed as an argument, | |
597 | then the generated file will contain accessor methods for all the | |
598 | slots in the classes and for global variables. The input class</p> | |
599 | <div class="code"><pre> | |
600 | class Foo { | |
601 | public: | |
602 | Foo(int i) : a(i) {} | |
603 | int a; | |
604 | int getMultBy(int i) { return a * i; } | |
605 | Foo getFooMultBy(int i) { return Foo(a * i); } | |
606 | }; | |
607 | Foo getFooPlus(int i) { return Foo(a + i); } | |
608 | </pre></div> | |
609 | ||
610 | <p> | |
611 | will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter) | |
612 | </p> | |
613 | ||
614 | <div class="targetlang"><pre> | |
615 | (define-class <Foo> (<swig>) | |
616 | (a #:allocation #:swig-virtual | |
617 | #:slot-ref primitive:Foo-a-get | |
618 | #:slot-set! primitive:Foo-a-set) | |
619 | #:metaclass <swig-metaclass> | |
620 | #:new-function primitive:new-Foo | |
621 | ) | |
622 | (define-method (getMultBy (swig_smob <Foo>) i) | |
623 | (primitive:Foo-getMultBy (slot-ref swig_smob 'smob) i)) | |
624 | (define-method (getFooMultBy (swig_smob <Foo>) i) | |
625 | (make <Foo> #:init-smob (primitive:Foo-getFooMultBy (slot-ref swig_smob 'smob) i))) | |
626 | ||
627 | (define-method (getFooPlus i) | |
628 | (make <Foo> #:init-smob (primitive:getFooPlus i))) | |
629 | ||
630 | (export <Foo> getMultBy getFooMultBy getFooPlus ) | |
631 | </pre></div> | |
632 | ||
633 | <p> | |
634 | and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter) | |
635 | </p> | |
636 | ||
637 | <div class="targetlang"><pre> | |
638 | (define-class <Foo> (<swig>) | |
639 | (a #:allocation #:swig-virtual | |
640 | #:slot-ref primitive:Foo-a-get | |
641 | #:slot-set! primitive:Foo-a-set | |
642 | <b>#:accessor a</b>) | |
643 | #:metaclass <swig-metaclass> | |
644 | #:new-function primitive:new-Foo | |
645 | ) | |
646 | (define-method (getMultBy (swig_smob <Foo>) i) | |
647 | (primitive:Foo-getMultBy (slot-ref swig_smob 'smob) i)) | |
648 | (define-method (getFooMultBy (swig_smob <Foo>) i) | |
649 | (make <Foo> #:init-smob (primitive:Foo-getFooMultBy (slot-ref swig_smob 'smob) i))) | |
650 | ||
651 | (define-method (getFooPlus i) | |
652 | (make <Foo> #:init-smob (primitive:getFooPlus i))) | |
653 | ||
654 | (export <Foo> <b>a</b> getMultBy getFooMultBy getFooPlus ) | |
655 | </pre></div> | |
656 | ||
657 | <p> | |
658 | which can then be used by this code | |
659 | </p> | |
660 | ||
661 | <div class="targetlang"><pre> | |
662 | ;; not using getters and setters | |
663 | (define foo (make <Foo> #:args '(45))) | |
664 | (slot-ref foo 'a) | |
665 | (slot-set! foo 'a 3) | |
666 | (getMultBy foo 4) | |
667 | (define foo2 (getFooMultBy foo 7)) | |
668 | (slot-ref foo 'a) | |
669 | (slot-ref (getFooPlus foo 4) 'a) | |
670 | ||
671 | ;; using getters and setters | |
672 | (define foo (make <Foo> #:args '(45))) | |
673 | (a foo) | |
674 | (set! (a foo) 5) | |
675 | (getMultBy foo 4) | |
676 | (a (getFooMultBy foo 7)) | |
677 | </pre></div> | |
678 | ||
679 | <p>Notice that constructor arguments are passed as a list after the <code>#:args</code> keyword. Hopefully in | |
680 | the future the following will be valid <code>(make <Foo> #:a 5 #:b 4)</code></p> | |
681 | ||
682 | <p>Also note that the order the declarations occur in the .i file make a difference. For example, | |
683 | </p> | |
684 | ||
685 | <div class="code"><pre> | |
686 | %module test | |
687 | ||
688 | %{ #include "foo.h" %} | |
689 | ||
690 | %inline %{ | |
691 | int someFunc(Foo &a) { | |
692 | ... | |
693 | } | |
694 | %} | |
695 | ||
696 | %include "foo.h" | |
697 | </pre></div> | |
698 | ||
699 | <p> | |
700 | This is a valid SWIG file it will work as you think it will for primitive support, but the generated | |
701 | GOOPS file will be broken. Since the <code>someFunc</code> definition is parsed by SWIG before all the | |
702 | declarations in foo.h, the generated GOOPS file will contain the definition of <code>someFunc()</code> | |
703 | before the definition of <Foo>. The generated GOOPS file would look like | |
704 | </p> | |
705 | ||
706 | <div class="targetlang"><pre> | |
707 | ;;... | |
708 | ||
709 | (define-method (someFunc (swig_smob <Foo>)) | |
710 | (primitive:someFunc (slot-ref swig_smob 'smob))) | |
711 | ||
712 | ;;... | |
713 | ||
714 | (define-class <Foo> (<swig>) | |
715 | ;;... | |
716 | ) | |
717 | ||
718 | ;;... | |
719 | </pre></div> | |
720 | ||
721 | <p> | |
722 | Notice that <Foo> is used before it is defined. The fix is to just put the | |
723 | <code>%import "foo.h"</code> before the <code>%inline</code> block. | |
724 | </p> | |
725 | ||
726 | <H3><a name="Guile_nn20"></a>18.10.1 Naming Issues</H3> | |
727 | ||
728 | ||
729 | <p>As you can see in the example above, there are potential naming conflicts. The default exported | |
730 | accessor for the <code>Foo::a</code> variable is named <code>a</code>. The name of the wrapper global | |
731 | function is <code>getFooPlus</code>. | |
732 | If the <code>-useclassprefix</code> option is passed to swig, the name of all accessors and member | |
733 | functions will be prepended with the class name. So the accessor will be called <code>Foo-a</code> and | |
734 | the member functions will be called <code>Foo-getMultBy</code>. Also, if the | |
735 | <code>-goopsprefix goops:</code> argument is passed to swig, every identifier will be prefixed by | |
736 | <code>goops:</code></p> | |
737 | ||
738 | <p>Two guile-modules are created by SWIG. The first module contains the primitive definitions | |
739 | of all the wrapped functions and variables, and is located either in the _wrap.cxx file (with <code>-Linkage | |
740 | module</code>) or in the scmstub file (if <code>-Linkage passive -scmstub</code>). The name of this | |
741 | guile-module is the swig-module name (given on the command line with the -module argument or with the | |
742 | %module directive) concatenated with the string "-primitive". For | |
743 | example, if <code>%module Test</code> is set in the swig interface file, the name of the guile-module in | |
744 | the scmstub or <code>-Linkage module</code> will be <code>Test-primitive</code>. Also, the scmstub | |
745 | file will be named <code>Test-primitive.scm</code>. | |
746 | The string "primitive" can be changed by the <code>-primsuffix</code> swig | |
747 | argument. So the same interface, with the <code>-primsuffix base</code> will produce a module called | |
748 | <code>Test-base</code>. | |
749 | The second generated guile-module contains all the GOOPS class definitions and is located in | |
750 | a file named <i>module</i>.scm in the directory specified with -outdir or the current directory. | |
751 | The name of this guile-module is the name of the | |
752 | swig-module (given on the command line or with the <code>%module</code> directive). | |
753 | In the previous example, the GOOPS definitions will be in a file named Test.scm.</p> | |
754 | ||
755 | <p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS | |
756 | guile-modules at the same time. To do this, you need to rename the exported symbols from one or both | |
757 | guile-modules. For example,</p> | |
758 | <div class="targetlang"><pre> | |
759 | (use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:))) | |
760 | (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:))) | |
761 | </pre></div> | |
762 | ||
763 | <p>TODO: Renaming class name prefixes?</p> | |
764 | ||
765 | <H3><a name="Guile_nn21"></a>18.10.2 Linking</H3> | |
766 | ||
767 | ||
768 | <p>The guile-modules generated above all need to be linked together. GOOPS support requires | |
769 | either passive or module linkage. The exported GOOPS guile-module will be the name of the swig-module | |
770 | and should be located in a file called <i>Module</i>.scm. This should be installed on the autoload | |
771 | path for guile, so that <code>(use-modules (<i>Package Module</i>))</code> will load everything needed. | |
772 | Thus, the top of the GOOPS guile-module will contain code to load everything needed by the interface | |
773 | (the shared library, the scmstub module, etc.). | |
774 | The <code>%goops</code> directive inserts arbitrary code into the generated GOOPS guile-module, and | |
775 | should be used to load the dependent libraries.</p> | |
776 | ||
777 | <p>This breaks up into three cases</p> | |
778 | <ul> | |
779 | <li><b>Passive Linkage without -scmstub</b>: Note that this linkage style has the potential for naming | |
780 | conflicts, since the primitive exported function and variable names are not wrapped in a guile-module | |
781 | and might conflict with names from the GOOPS guile-module (see above). Pass the -goopsprefix | |
782 | argument to solve this problem. If the <code>-exportprimitive</code> option is passed to SWIG the | |
783 | <code>(export ...)</code> code that would be exported into the scmstub file is exported at the bottom | |
784 | of the generated GOOPS guile-module. | |
785 | The <code>%goops</code> directive should contain code to load the .so library. | |
786 | ||
787 | <div class="code"><pre> | |
788 | %goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} | |
789 | </pre></div> | |
790 | ||
791 | <p> | |
792 | Produces the following code at the top of the generated GOOPS guile-module | |
793 | (with the <code>-package my/modules -module foo</code> command line arguments) | |
794 | </p> | |
795 | ||
796 | <div class="targetlang"><pre> | |
797 | (define-module (my modules foo)) | |
798 | ||
799 | ;; %goops directive goes here | |
800 | (load-extension "./foo.so" "scm_init_my_modules_foo_module") | |
801 | ||
802 | (use-modules (oop goops) (Swig common)) | |
803 | </pre></div> | |
804 | </li> | |
805 | ||
806 | <li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be | |
807 | <code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code> | |
808 | argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive, | |
809 | which will then be added to the scmstub file. | |
810 | Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code> | |
811 | into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the | |
812 | <code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain | |
813 | whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p> | |
814 | ||
815 | <div class="targetlang"><pre> | |
816 | %scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} | |
817 | // only include the following definition if (my modules foo) cannot | |
818 | // be loaded automatically | |
819 | %goops %{ | |
820 | (primitive-load "/path/to/foo-primitive.scm") | |
821 | (primitive-load "/path/to/Swig/common.scm") | |
822 | %} | |
823 | </pre></div> | |
824 | ||
825 | <p> | |
826 | Produces the following code at the top of the generated GOOPS guile-module | |
827 | </p> | |
828 | ||
829 | <div class="targetlang"><pre> | |
830 | (define-module (my modules foo)) | |
831 | ||
832 | ;; %goops directive goes here (if any) | |
833 | (primitive-load "/path/to/foo-primitive.scm") | |
834 | (primitive-load "/path/to/Swig/common.scm") | |
835 | ||
836 | (use-modules (oop goops) (Swig common)) | |
837 | (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc | |
838 | 'primitive:))) | |
839 | ||
840 | </pre></div> | |
841 | </li> | |
842 | ||
843 | <li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file. | |
844 | Swig will also automatically generate the line <code>(use-modules | |
845 | (<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code> | |
846 | directive should contain whatever code is needed to get that module loaded into guile.</p> | |
847 | ||
848 | <div class="code"><pre> | |
849 | %goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} | |
850 | </pre></div> | |
851 | ||
852 | <p> | |
853 | Produces the following code at the top of the generated GOOPS guile-module | |
854 | </p> | |
855 | ||
856 | <div class="targetlang"><pre> | |
857 | (define-module (my modules foo)) | |
858 | ||
859 | ;; %goops directive goes here (if any) | |
860 | (load-extension "./foo.so" "scm_init_my_modules_foo_module") | |
861 | ||
862 | (use-modules (oop goops) (Swig common)) | |
863 | (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc | |
864 | 'primitive:))) | |
865 | ||
866 | </pre></div> | |
867 | </li> | |
868 | </ul> | |
869 | ||
870 | <p><b>(Swig common)</b>: The generated GOOPS guile-module also imports definitions from the | |
871 | (Swig common) guile-module. | |
872 | This module is included with SWIG and should be installed by SWIG into the autoload path for | |
873 | guile (based on the configure script and whatever arguments are passed). If it is not, then the | |
874 | <code>%goops</code> directive also needs to contain code to load the <code>common.scm</code> file | |
875 | into guile. Also note that if you are trying to install the generated wrappers on a computer without | |
876 | SWIG installed, you will need to include the common.swg file along with the install.</p> | |
877 | ||
878 | <p><b>Multiple Modules</b>: Type dependencies between modules is supported. For example, if | |
879 | <code>mod1</code> includes definitions of some classes, and <code>mod2</code> includes some classes | |
880 | derived from classes in <code>mod1</code>, the generated GOOPS file for <code>mod2</code> will declare | |
881 | the correct superclasses. The only problem is that since <code>mod2</code> uses symbols from | |
882 | <code>mod1</code>, the <code>mod2</code> GOOPS file must include a <code>(use-modules (mod2))</code>. | |
883 | Currently, SWIG does not automatically export this line; it must be included in the <code>%goops</code> | |
884 | directive of <code>mod2</code>. Maybe in the future SWIG can detect dependencies and export this line. | |
885 | (how do other language modules handle this problem?)</p> | |
886 | ||
887 | </body> | |
888 | </html> |