Doc/Manual/Guile.html

   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>20 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>20.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>20.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 &gt;= 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>20.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>20.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>20.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>20.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>20.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>20.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>20.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>20.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 <p>Constants are exported as a function that returns the value.  The
 409 %feature("constasvar") can be applied to any constant, immutable variable, or enum.
 410 Instead of exporting the constant as a function that must be called, the
 411 constant will appear as a scheme variable. See
 412 <a href="Customization.html#features">Features and the %feature directive</a>
 413 for info on how to apply the %feature.</p>
 414
 415 <H2><a name="Guile_nn12"></a>20.6 Representation of pointers as smobs</H2>
 416
 417
 418 <p>
 419 For pointer types, SWIG uses Guile smobs. SWIG smobs print
 420 like this: <code>#&lt;swig struct xyzzy * 0x1234affe&gt;</code>  Two of
 421 them are <code>equal?</code> if and only if they have the same type
 422 and value.
 423
 424 <p>
 425 To construct a Scheme object from a C pointer, the wrapper code calls
 426 the function <code>SWIG_NewPointerObj()</code>, passing a pointer to a
 427 struct representing the pointer type. The type index to store in the
 428 upper half of the CAR is read from this struct.
 429 To get the pointer represented by a smob, the wrapper code calls the
 430 function <code>SWIG_ConvertPtr()</code>, passing a pointer to a struct
 431 representing the expected pointer type.  See also
 432 <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>.
 433 If the Scheme object passed was not a SWIG smob representing a compatible
 434 pointer, a <code>wrong-type-arg</code> exception is raised.
 435
 436 <H3><a name="Guile_nn13"></a>20.6.1 GH Smobs</H3>
 437
 438
 439 <p>
 440 In earlier versions of SWIG, C pointers were represented as Scheme
 441 strings containing a hexadecimal rendering of the pointer value and a
 442 mangled type name.  As Guile allows registering user types, so-called
 443 "smobs" (small objects), a much cleaner representation has been
 444 implemented now.  The details will be discussed in the following.
 445 </p>
 446
 447 <p> A smob is a cons cell where the lower half of the CAR contains the smob type
 448 tag, while the upper half of the CAR and the whole CDR are available. Every
 449 module creates its own smob type in the clientdata field of the module. So the
 450 lower 16 bits of the car of the smob store the tag and the upper 16 bits store
 451 the index this type is in the array. We can then, given a smob, find its
 452 swig_type_info struct by using the tag (lower 16 bits of car) to find which
 453 module this type is in (since each tag is unique for the module). Then we use
 454 the upper 16 bits to index into the array of types attached to this module.
 455 Looking up the module from the tag is worst case O(# of modules) but average
 456 case O(1). This is because the modules are stored in a circularly linked list,
 457 and when we start searching the modules for the tag, we start looking with the
 458 module that the function doing the lookup is in. SWIG_Guile_ConvertPtr() takes
 459 as its first argument the swig_module_info * of the calling function, which is
 460 where we start comparing tags. Most types will be looked up in the same module
 461 that created them, so the first module we check will most likely be correct.
 462 Once we have a swig_type_info structure, we loop through the linked list of
 463 casts, using pointer comparisons.</p>
 464
 465 <H3><a name="Guile_nn14"></a>20.6.2 SCM Smobs</H3>
 466
 467
 468 <p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
 469 The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
 470 The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described
 471 below.  Each smob has the same format, which is a double cell created by SCM_NEWSMOB2()
 472 The first word of data is the pointer to the object and the second word of data is the swig_type_info *
 473 structure describing this type.  This is a lot easier than the GH interface above because we can store
 474 a pointer to the type info structure right in the type.  With the GH interface, there was not enough
 475 room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address"
 476 in the smob tag.  If a generated GOOPS module has been loaded, smobs will be wrapped by the corresponding
 477 GOOPS class.</p>
 478
 479
 480 <H3><a name="Guile_nn15"></a>20.6.3 Garbage Collection</H3>
 481
 482
 483 <p>Garbage collection is a feature of the new SCM interface, and it is automatically included
 484 if you pass the "-scm" flag to swig.  Thus the swig garbage collection support requires guile &gt;1.6.
 485 Garbage collection works like this.  Every swig_type_info structure stores in its clientdata field a pointer
 486 to the destructor for this type.  The destructor is the generated wrapper around the delete function.
 487 So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
 488 the wrapped delete function.  So the only way to delete an object is from the garbage collector, since the
 489 delete function is not available to scripts.  How swig determines if a type should be garbage collected
 490 is exactly like described in <a href="Customization.html#ownership">
 491 Object ownership and %newobject</a> in the SWIG manual.  All typemaps use an $owner var, and
 492 the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
 493
 494 <H2><a name="Guile_nn16"></a>20.7 Exception Handling</H2>
 495
 496
 497 <p>
 498 SWIG code calls <code>scm_error</code> on exception, using the following
 499 mapping:
 500
 501 <div class="code">
 502 <pre>
 503       MAP(SWIG_MemoryError,     "swig-memory-error");
 504       MAP(SWIG_IOError,         "swig-io-error");
 505       MAP(SWIG_RuntimeError,    "swig-runtime-error");
 506       MAP(SWIG_IndexError,      "swig-index-error");
 507       MAP(SWIG_TypeError,       "swig-type-error");
 508       MAP(SWIG_DivisionByZero,  "swig-division-by-zero");
 509       MAP(SWIG_OverflowError,   "swig-overflow-error");
 510       MAP(SWIG_SyntaxError,     "swig-syntax-error");
 511       MAP(SWIG_ValueError,      "swig-value-error");
 512       MAP(SWIG_SystemError,     "swig-system-error");
 513 </pre>
 514 </div>
 515
 516 <p>
 517 The default when not specified here is to use "swig-error".
 518 See Lib/exception.i for details.
 519
 520 <H2><a name="Guile_nn17"></a>20.8 Procedure documentation</H2>
 521
 522
 523 <p>If invoked with the command-line option <code>-procdoc
 524 <var>file</var></code>, SWIG creates documentation strings for the
 525 generated wrapper functions, describing the procedure signature and
 526 return value, and writes them to <var>file</var>. You need Guile 1.4
 527 or later to make use of the documentation files.
 528
 529 <p>SWIG can generate documentation strings in three formats, which are
 530 selected via the command-line option <code>-procdocformat
 531 <var>format</var></code>:
 532 <ul>
 533 <li><code>guile-1.4</code> (default): Generates a format suitable for Guile 1.4.
 534 <li><code>plain</code>: Generates a format suitable for Guile 1.4.1 and
 535 later.
 536 <li><code>texinfo</code>: Generates texinfo source, which must be run
 537 through texinfo in order to get a format suitable for Guile 1.4.1 and
 538 later.
 539 </ul>
 540
 541 <p>You need to register the generated documentation file with Guile
 542 like this:
 543
 544 <div class="targetlang">
 545 <pre>
 546 (use-modules (ice-9 documentation))
 547 (set! documentation-files
 548       (cons "<var>file</var>" documentation-files))
 549 </pre>
 550 </div>
 551
 552 <p>Documentation strings can be configured using the Guile-specific
 553 typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
 554 details.
 555
 556 <H2><a name="Guile_nn18"></a>20.9 Procedures with setters</H2>
 557
 558
 559 <p>For global variables, SWIG creates a single wrapper procedure
 560 <code>(<var>variable</var> :optional value)</code>, which is used for
 561 both getting and setting the value. For struct members, SWIG creates
 562 two wrapper procedures <code>(<var>struct</var>-<var>member</var>-get
 563 pointer)</code> and <code>(<var>struct-member</var>-set pointer value)</code>.
 564
 565 <p>If invoked with the command-line option <code>-emit-setters</code>
 566 (<em>recommended</em>),
 567 SWIG will additionally create procedures with setters. For global
 568 variables, the procedure-with-setter <code><var>variable</var></code>
 569 is created, so you can use <code>(<var>variable</var>)</code> to get
 570 the value and <code>(set! (<var>variable</var>)
 571 <var>value</var>)</code> to set it. For struct members, the
 572 procedure-with-setter <code><var>struct</var>-<var>member</var></code>
 573 is created, so you can use <code>(<var>struct</var>-<var>member</var>
 574 <var>pointer</var>)</code> to get the value and <code>(set!
 575 (<var>struct</var>-<var>member</var> <var>pointer</var>)
 576 <var>value</var>)</code> to set it.
 577
 578 <p>If invoked with the command-line option <code>-only-setters</code>,
 579 SWIG will <em>only</em> create procedures with setters, i.e., for
 580 struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
 581 pointer)</code> and <code>(<var>struct-member</var>-set pointer
 582 value)</code> are <em>not</em> generated.
 583
 584 <H2><a name="Guile_nn19"></a>20.10 GOOPS Proxy Classes</H2>
 585
 586
 587 <p>SWIG can also generate classes and generic functions for use with
 588 Guile's Object-Oriented Programming System (GOOPS).  GOOPS is a
 589 sophisticated object system in the spirit of the Common Lisp Object
 590 System (CLOS).
 591
 592 <p>GOOPS support is
 593 only available with the new SCM interface (enabled with the
 594 <code>-scm</code> command-line option of SWIG).  To enable GOOPS
 595 support, pass the <code>-proxy</code> argument to
 596 swig.  This will export the GOOPS wrapper definitions into the
 597 <code><i>module</i>.scm</code> file in the directory specified by -outdir or the
 598 current directory.  GOOPS support requires either passive or module linkage.</p>
 599
 600 <p>The generated file will contain definitions of GOOPS classes mimicking the C++ class hierarchy.
 601 <p>Enabling GOOPS support implies <code>-emit-setters</code>.
 602
 603 <p>If <code>-emit-slot-accessors</code> is also passed as an argument,
 604 then the generated file will contain accessor methods for all the
 605 slots in the classes and for global variables.  The input class</p>
 606 <div class="code"><pre>
 607   class Foo {
 608     public:
 609       Foo(int i) : a(i) {}
 610       int a;
 611       int getMultBy(int i) { return a * i; }
 612       Foo getFooMultBy(int i) { return Foo(a * i); }
 613   };
 614   Foo getFooPlus(int i) { return Foo(a + i); }
 615 </pre></div>
 616
 617 <p>
 618 will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
 619 </p>
 620
 621 <div class="targetlang"><pre>
 622 (define-class &lt;Foo&gt; (&lt;swig&gt;)
 623   (a #:allocation #:swig-virtual
 624      #:slot-ref primitive:Foo-a-get
 625      #:slot-set! primitive:Foo-a-set)
 626   #:metaclass &lt;swig-metaclass&gt;
 627   #:new-function primitive:new-Foo
 628 )
 629 (define-method (getMultBy (swig_smob &lt;Foo&gt;) i)
 630   (primitive:Foo-getMultBy  (slot-ref swig_smob 'smob) i))
 631 (define-method (getFooMultBy (swig_smob &lt;Foo&gt;) i)
 632   (make &lt;Foo&gt; #:init-smob (primitive:Foo-getFooMultBy  (slot-ref swig_smob 'smob) i)))
 633
 634 (define-method (getFooPlus i)
 635   (make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
 636
 637 (export &lt;Foo&gt; getMultBy getFooMultBy getFooPlus )
 638 </pre></div>
 639
 640 <p>
 641 and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
 642 </p>
 643
 644 <div class="targetlang"><pre>
 645 (define-class &lt;Foo&gt; (&lt;swig&gt;)
 646   (a #:allocation #:swig-virtual
 647      #:slot-ref primitive:Foo-a-get
 648      #:slot-set! primitive:Foo-a-set
 649      <b>#:accessor a</b>)
 650   #:metaclass &lt;swig-metaclass&gt;
 651   #:new-function primitive:new-Foo
 652 )
 653 (define-method (getMultBy (swig_smob &lt;Foo&gt;) i)
 654   (primitive:Foo-getMultBy  (slot-ref swig_smob 'smob) i))
 655 (define-method (getFooMultBy (swig_smob &lt;Foo&gt;) i)
 656   (make &lt;Foo&gt; #:init-smob (primitive:Foo-getFooMultBy  (slot-ref swig_smob 'smob) i)))
 657
 658 (define-method (getFooPlus i)
 659   (make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
 660
 661 (export &lt;Foo&gt; <b>a</b> getMultBy getFooMultBy getFooPlus )
 662 </pre></div>
 663
 664 <p>
 665 which can then be used by this code
 666 </p>
 667
 668 <div class="targetlang"><pre>
 669 ;; not using getters and setters
 670 (define foo (make &lt;Foo&gt; #:args '(45)))
 671 (slot-ref foo 'a)
 672 (slot-set! foo 'a 3)
 673 (getMultBy foo 4)
 674 (define foo2 (getFooMultBy foo 7))
 675 (slot-ref foo 'a)
 676 (slot-ref (getFooPlus foo 4) 'a)
 677
 678 ;; using getters and setters
 679 (define foo (make &lt;Foo&gt; #:args '(45)))
 680 (a foo)
 681 (set! (a foo) 5)
 682 (getMultBy foo 4)
 683 (a (getFooMultBy foo 7))
 684 </pre></div>
 685
 686 <p>Notice that constructor arguments are passed as a list after the <code>#:args</code> keyword.  Hopefully in
 687 the future the following will be valid <code>(make &lt;Foo&gt; #:a 5 #:b 4)</code></p>
 688
 689 <p>Also note that the order the declarations occur in the .i file make a difference.  For example,
 690 </p>
 691
 692 <div class="code"><pre>
 693 %module test
 694
 695 %{ #include "foo.h" %}
 696
 697 %inline %{
 698   int someFunc(Foo &amp;a) {
 699     ...
 700   }
 701 %}
 702
 703 %include "foo.h"
 704 </pre></div>
 705
 706 <p>
 707 This is a valid SWIG file it will work as you think it will for primitive support, but the generated
 708 GOOPS file will be broken.  Since the <code>someFunc</code> definition is parsed by SWIG before all the
 709 declarations in foo.h, the generated GOOPS file will contain the definition of <code>someFunc()</code>
 710 before the definition of &lt;Foo&gt;.  The generated GOOPS file would look like
 711 </p>
 712
 713 <div class="targetlang"><pre>
 714 ;;...
 715
 716 (define-method (someFunc (swig_smob &lt;Foo&gt;))
 717   (primitive:someFunc (slot-ref swig_smob 'smob)))
 718
 719 ;;...
 720
 721 (define-class &lt;Foo&gt; (&lt;swig&gt;)
 722   ;;...
 723 )
 724
 725 ;;...
 726 </pre></div>
 727
 728 <p>
 729 Notice that &lt;Foo&gt; is used before it is defined.  The fix is to just put the
 730 <code>%import "foo.h"</code> before the <code>%inline</code> block.
 731 </p>
 732
 733 <H3><a name="Guile_nn20"></a>20.10.1 Naming Issues</H3>
 734
 735
 736 <p>As you can see in the example above, there are potential naming conflicts.  The default exported
 737 accessor for the <code>Foo::a</code> variable is named <code>a</code>.  The name of the wrapper global
 738 function is <code>getFooPlus</code>.
 739 If the <code>-useclassprefix</code> option is passed to swig, the name of all accessors and member
 740 functions will be prepended with the class name.  So the accessor will be called <code>Foo-a</code> and
 741 the member functions will be called <code>Foo-getMultBy</code>.  Also, if the
 742 <code>-goopsprefix goops:</code> argument is passed to swig, every identifier will be prefixed by
 743 <code>goops:</code></p>
 744
 745 <p>Two guile-modules are created by SWIG.  The first module contains the primitive definitions
 746 of all the wrapped functions and variables, and is located either in the _wrap.cxx file (with <code>-Linkage
 747 module</code>) or in the scmstub file (if <code>-Linkage passive -scmstub</code>).  The name of this
 748 guile-module is the swig-module name (given on the command line with the -module argument or with the
 749 %module directive) concatenated with the string "-primitive".  For
 750 example, if <code>%module Test</code> is set in the swig interface file, the name of the guile-module in
 751 the scmstub or <code>-Linkage module</code> will be <code>Test-primitive</code>.  Also, the scmstub
 752 file will be named <code>Test-primitive.scm</code>.
 753 The string "primitive" can be changed by the <code>-primsuffix</code> swig
 754 argument.  So the same interface, with the <code>-primsuffix base</code> will produce a module called
 755 <code>Test-base</code>.
 756 The second generated guile-module contains all the GOOPS class definitions and is located in
 757 a file named <i>module</i>.scm in the directory specified with -outdir or the current directory.
 758 The name of this guile-module is the name of the
 759 swig-module (given on the command line or with the <code>%module</code> directive).
 760 In the previous example, the GOOPS definitions will be in a file named Test.scm.</p>
 761
 762 <p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS
 763 guile-modules at the same time.  To do this, you need to rename the exported symbols from one or both
 764 guile-modules.  For example,</p>
 765 <div class="targetlang"><pre>
 766 (use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
 767 (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
 768 </pre></div>
 769
 770 <p>TODO: Renaming class name prefixes?</p>
 771
 772 <H3><a name="Guile_nn21"></a>20.10.2 Linking</H3>
 773
 774
 775 <p>The guile-modules generated above all need to be linked together.  GOOPS support requires
 776 either passive or module linkage.  The exported GOOPS guile-module will be the name of the swig-module
 777 and should be located in a file called <i>Module</i>.scm.  This should be installed on the autoload
 778 path for guile, so that <code>(use-modules (<i>Package Module</i>))</code> will load everything needed.
 779 Thus, the top of the GOOPS guile-module will contain code to load everything needed by the interface
 780 (the shared library, the scmstub module, etc.).
 781 The <code>%goops</code> directive inserts arbitrary code into the generated GOOPS guile-module, and
 782 should be used to load the dependent libraries.</p>
 783
 784 <p>This breaks up into three cases</p>
 785 <ul>
 786 <li><b>Passive Linkage without -scmstub</b>:  Note that this linkage style has the potential for naming
 787 conflicts, since the primitive exported function and variable names are not wrapped in a guile-module
 788 and might conflict with names from the GOOPS guile-module (see above).  Pass the -goopsprefix
 789 argument to solve this problem.  If the <code>-exportprimitive</code> option is passed to SWIG the
 790 <code>(export ...)</code> code that would be exported into the scmstub file is exported at the bottom
 791 of the generated GOOPS guile-module.
 792 The <code>%goops</code> directive should contain code to load the .so library.
 793
 794 <div class="code"><pre>
 795 %goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
 796 </pre></div>
 797
 798 <p>
 799 Produces the following code at the top of the generated GOOPS guile-module
 800 (with the <code>-package my/modules -module foo</code> command line arguments)
 801 </p>
 802
 803 <div class="targetlang"><pre>
 804 (define-module (my modules foo))
 805
 806 ;; %goops directive goes here
 807 (load-extension "./foo.so" "scm_init_my_modules_foo_module")
 808
 809 (use-modules (oop goops) (Swig common))
 810 </pre></div>
 811 </li>
 812
 813 <li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
 814 <code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
 815 argument.  The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
 816 which will then be added to the scmstub file.
 817 Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
 818 into the GOOPS guile-module.  So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
 819 <code>%goops</code> directive can be empty.  Otherwise, the <code>%goops</code> directive should contain
 820 whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
 821
 822 <div class="targetlang"><pre>
 823 %scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
 824 // only include the following definition if (my modules foo) cannot
 825 // be loaded automatically
 826 %goops %{
 827   (primitive-load "/path/to/foo-primitive.scm")
 828   (primitive-load "/path/to/Swig/common.scm")
 829 %}
 830 </pre></div>
 831
 832 <p>
 833 Produces the following code at the top of the generated GOOPS guile-module
 834 </p>
 835
 836 <div class="targetlang"><pre>
 837 (define-module (my modules foo))
 838
 839 ;; %goops directive goes here (if any)
 840 (primitive-load "/path/to/foo-primitive.scm")
 841 (primitive-load "/path/to/Swig/common.scm")
 842
 843 (use-modules (oop goops) (Swig common))
 844 (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
 845                                                        'primitive:)))
 846
 847 </pre></div>
 848 </li>
 849
 850 <li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
 851 Swig will also automatically generate the line <code>(use-modules
 852 (<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module.  Again the <code>%goops</code>
 853 directive should contain whatever code is needed to get that module loaded into guile.</p>
 854
 855 <div class="code"><pre>
 856 %goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
 857 </pre></div>
 858
 859 <p>
 860 Produces the following code at the top of the generated GOOPS guile-module
 861 </p>
 862
 863 <div class="targetlang"><pre>
 864 (define-module (my modules foo))
 865
 866 ;; %goops directive goes here (if any)
 867 (load-extension "./foo.so" "scm_init_my_modules_foo_module")
 868
 869 (use-modules (oop goops) (Swig common))
 870 (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
 871                                                          'primitive:)))
 872
 873 </pre></div>
 874 </li>
 875 </ul>
 876
 877 <p><b>(Swig common)</b>: The generated GOOPS guile-module also imports definitions from the
 878 (Swig common) guile-module.
 879 This module is included with SWIG and should be installed by SWIG into the autoload path for
 880 guile (based on the configure script and whatever arguments are passed).  If it is not, then the
 881 <code>%goops</code> directive also needs to contain code to load the <code>common.scm</code> file
 882 into guile.  Also note that if you are trying to install the generated wrappers on a computer without
 883 SWIG installed, you will need to include the common.swg file along with the install.</p>
 884
 885 <p><b>Multiple Modules</b>:  Type dependencies between modules is supported.  For example, if
 886 <code>mod1</code> includes definitions of some classes, and <code>mod2</code> includes some classes
 887 derived from classes in <code>mod1</code>, the generated GOOPS file for <code>mod2</code> will declare
 888 the correct superclasses.  The only problem is that since <code>mod2</code> uses symbols from
 889 <code>mod1</code>, the <code>mod2</code> GOOPS file must include a <code>(use-modules (mod2))</code>.
 890 Currently, SWIG does not automatically export this line;  it must be included in the <code>%goops</code>
 891 directive of <code>mod2</code>.  Maybe in the future SWIG can detect dependencies and export this line.
 892 (how do other language modules handle this problem?)</p>
 893
 894 </body>
 895 </html>