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